@owlmeans/create-app 0.1.18-rc.15 → 0.1.18-rc.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/create-app",
-  "version": "0.1.18-rc.15",
+  "version": "0.1.18-rc.16",
   "license": "MIT",
   "description": "Scaffold a fullstack OwlMeans Common app — common + api + web workspaces, shadcn UI navigation/layout, no auth, and a session-scoped in-memory resource, or --bare for the demo-free shell. Also usable programmatically via scaffold(). Deploys agent skills via @owlmeans/agent-skills by default.",
   "type": "module",
@@ -30,7 +30,7 @@
     "template"
   ],
   "dependencies": {
-    "@owlmeans/agent-skills": "^0.1.18-rc.12"
+    "@owlmeans/agent-skills": "^0.1.18-rc.13"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",

package/template/AGENTS.md

@@ -79,6 +79,14 @@ package (in the installed packages and at https://github.com/owlmeans/common) or
 already solves the problem **before** proposing a third-party library or a custom solution, and
 simplify whatever you do write. This is required for every planning and development task.
 
+## Runtime config advertisement
+
+The config endpoint is default-deny. A backend config field reaches the browser only when the
+package that owns its browser consumer imports `apiConfigPlugin({ allow, deny? })` from
+`@owlmeans/api-config` at module scope. Name public nested fields precisely; use `every()` and a
+nested `deny` selector when a public collection carries a credential. Databases, queues, SMTP,
+tokens, secrets and internal addresses never belong in an `allow` selector.
+
 ## Skills
 
 Reusable guidance lives in `.agents/skills/<name>/SKILL.md`, deployed by `@owlmeans/agent-skills`

package/template/_agents/skills/reuse-code/SKILL.md

@@ -57,7 +57,7 @@ other `@owlmeans/*` packages:
 
 ```json
 "dependencies": {
-  "@owlmeans/queue": "^0.1.18-rc.9"
+  "@owlmeans/queue": "^0.1.18-rc.10"
 }
 ```
 

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

@@ -1,13 +1,14 @@
 import { randomUUID } from 'node:crypto'
-import { handleBody } from '@owlmeans/server-app'
-import type { AddItemPayload, SessionItem, SessionParams } from '__APP_SLUG__-common'
+import { handlers } from '@owlmeans/server-app'
+import { session, type SessionItem } from '__APP_SLUG__-common'
 import { SESSION_ITEMS } from '../../consts.js'
 import type { Context } from '../../types.js'
 
-export const add = handleBody<AddItemPayload>(async (payload, context, req) => {
-  const ctx = context as Context
-  const { sid } = req.params as SessionParams
-  const resource = ctx.getStaticResource<SessionItem>(SESSION_ITEMS)
+const handle = handlers<Context>()
+
+export const add = handle.body(session.add, async (payload, context, request) => {
+  const { sid } = request.params
+  const resource = context.getStaticResource<SessionItem>(SESSION_ITEMS)
 
   const item: SessionItem = {
     id: randomUUID(),

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

@@ -1,11 +1,12 @@
-import { handleParams } from '@owlmeans/server-app'
-import type { SessionItem, SessionParams } from '__APP_SLUG__-common'
+import { handlers } from '@owlmeans/server-app'
+import { session, type SessionItem } from '__APP_SLUG__-common'
 import { SESSION_ITEMS } from '../../consts.js'
 import type { Context } from '../../types.js'
 
-export const list = handleParams<SessionParams>(async (params, context) => {
-  const ctx = context as Context
-  const resource = ctx.getStaticResource<SessionItem>(SESSION_ITEMS)
+const handle = handlers<Context>()
+
+export const list = handle.params(session.list, async (params, context) => {
+  const resource = context.getStaticResource<SessionItem>(SESSION_ITEMS)
 
   // The resource answers the whole question — this session's items, newest first.
   const { items } = await resource.list(

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

@@ -1,11 +1,12 @@
-import { handleParams } from '@owlmeans/server-app'
-import type { ItemParams, SessionItem } from '__APP_SLUG__-common'
+import { handlers } from '@owlmeans/server-app'
+import { session, type SessionItem } from '__APP_SLUG__-common'
 import { SESSION_ITEMS } from '../../consts.js'
 import type { Context } from '../../types.js'
 
-export const remove = handleParams<ItemParams>(async (params, context) => {
-  const ctx = context as Context
-  const resource = ctx.getStaticResource<SessionItem>(SESSION_ITEMS)
+const handle = handlers<Context>()
+
+export const remove = handle.params(session.remove, async (params, context) => {
+  const resource = context.getStaticResource<SessionItem>(SESSION_ITEMS)
 
   const existing = await resource.load(params.id)
   // Only remove the item if it belongs to the requesting session.

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

@@ -1,6 +1,5 @@
-import { entrypoints } from '@owlmeans/server-app'
+import { elevate, entrypoints } from '@owlmeans/server-app'
 import { sharedEntrypoints } from '__APP_SLUG__-common'
 
-// Handlers attach to the shared declarations, never to a route re-declared here:
-// `elevate(sharedEntrypoints, alias, handler)` from '@owlmeans/server-app'.
-export const appEntrypoints = [...entrypoints, ...sharedEntrypoints]
+// Handlers bind to a protocol; a bare shell starts without any implementations.
+export const appEntrypoints = [...entrypoints, ...elevate(sharedEntrypoints, [])]

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

@@ -1,11 +1,8 @@
 import { elevate, entrypoints } from '@owlmeans/server-app'
-import { session, sessionEntrypoints } from '__APP_SLUG__-common'
+import { 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)
+// Each handler is already bound to its protocol; elevation materializes the local server entries.
+const sessionModules = elevate(sessionEntrypoints, [handlers.list, handlers.add, handlers.remove])
 
-export const appEntrypoints = [...entrypoints, ...sessionEntrypoints]
+export const appEntrypoints = [...entrypoints, ...sessionModules]

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

@@ -6,17 +6,3 @@ export const APP_API = '__APP_SLUG__-api'
 /** Local development ports. */
 export const WEB_PORT = 3001
 export const API_PORT = 3000
-
-/** Backend (API) entrypoint identifiers. */
-export const session = {
-  base: '__APP_SLUG__:api:session',
-  list: '__APP_SLUG__:api:session:list',
-  add: '__APP_SLUG__:api:session:add',
-  remove: '__APP_SLUG__:api:session:remove',
-}
-
-/** Frontend (web) entrypoint identifiers. */
-export const web = {
-  session: '__APP_SLUG__:web:session',
-  about: '__APP_SLUG__:web:about',
-}

package/template/sources/common/src/entrypoints.bare.ts

@@ -1,8 +1,8 @@
-import type { CommonEntrypoint } from '@owlmeans/entrypoint'
+import type { EntrypointProtocol } from '@owlmeans/entrypoint'
 
 /**
  * The entrypoint declarations both sides share: the api elevates them with handlers, the web
  * elevates them with screens or just calls them. Routes resolve under the api service `base`
  * (`/api`), so an `entrypoint(route(alias, '/items', ...))` added here answers on `/api/items`.
  */
-export const sharedEntrypoints: CommonEntrypoint[] = []
+export const sharedEntrypoints: EntrypointProtocol[] = []

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

@@ -1,26 +1,56 @@
-import { body, entrypoint, filter, params } from '@owlmeans/entrypoint'
-import { route, RouteMethod } from '@owlmeans/route'
-import { session } from './consts.js'
+import { contract, openProtocol, protocol, protocols, typed } from '@owlmeans/entrypoint'
+import { route, RouteMethod, frontend } from '@owlmeans/route'
 import { AddItemSchema, ItemParamsSchema, SessionParamsSchema } from './schemas.js'
-import type { AddItemPayload, ItemParams, SessionParams } from './types.js'
+import type { SessionItem } from './types.js'
+
+const aliases = {
+  session: {
+    base: '__APP_SLUG__:api:session',
+    list: '__APP_SLUG__:api:session:list',
+    add: '__APP_SLUG__:api:session:add',
+    remove: '__APP_SLUG__:api:session:remove',
+  },
+  web: {
+    base: '__APP_SLUG__:web:base',
+    home: '__APP_SLUG__:web:home',
+    session: '__APP_SLUG__:web:session',
+    about: '__APP_SLUG__:web:about',
+  },
+}
+
+const sessionBase = protocol(route(aliases.session.base, '/session'), contract())
+const webBase = openProtocol(route(aliases.web.base, '/', frontend()))
 
 /**
  * Shared entrypoint declarations. The api elevates these with handlers; the web
  * 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 sessionEntrypoints = [
-  entrypoint(route(session.base, '/session')),
-  entrypoint(
-    route(session.list, '/:sid/items', { parent: session.base, method: RouteMethod.GET }),
-    filter(params<SessionParams>(SessionParamsSchema)),
+export const session = {
+  base: sessionBase,
+  list: protocol(
+    route(aliases.session.list, '/:sid/items', { parent: sessionBase, method: RouteMethod.GET }),
+    contract.request({ params: SessionParamsSchema }, typed<SessionItem[]>()),
   ),
-  entrypoint(
-    route(session.add, '/:sid/items', { parent: session.base, method: RouteMethod.POST }),
-    filter(params<SessionParams>(SessionParamsSchema, body<AddItemPayload>(AddItemSchema))),
+  add: protocol(
+    route(aliases.session.add, '/:sid/items', { parent: sessionBase, method: RouteMethod.POST }),
+    contract.request({
+      params: SessionParamsSchema,
+      body: AddItemSchema,
+    }, typed<SessionItem>()),
   ),
-  entrypoint(
-    route(session.remove, '/:sid/items/:id', { parent: session.base, method: RouteMethod.DELETE }),
-    filter(params<ItemParams>(ItemParamsSchema)),
+  remove: protocol(
+    route(aliases.session.remove, '/:sid/items/:id', { parent: sessionBase, method: RouteMethod.DELETE }),
+    contract.request({ params: ItemParamsSchema }, typed<{ removed: boolean }>()),
   ),
-]
+}
+
+/** Frontend routes are protocol declarations too; their renderer is bound by the web project. */
+export const web = {
+  base: webBase,
+  home: openProtocol(route(aliases.web.home, '/', frontend({ default: true, parent: webBase }))),
+  session: openProtocol(route(aliases.web.session, '/session', frontend({ parent: webBase }))),
+  about: openProtocol(route(aliases.web.about, '/about', frontend({ parent: webBase }))),
+}
+
+export const sessionEntrypoints = protocols(session)

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

@@ -1,25 +1,25 @@
-import type { JSONSchemaType } from 'ajv'
+import { schema } from '@owlmeans/entrypoint'
 import type { AddItemPayload, ItemParams, SessionParams } from './types.js'
 
-export const AddItemSchema: JSONSchemaType<AddItemPayload> = {
+export const AddItemSchema = schema<AddItemPayload>({
   type: 'object',
   properties: {
     text: { type: 'string', minLength: 1, maxLength: 280 },
   },
   required: ['text'],
   additionalProperties: false,
-}
+})
 
-export const SessionParamsSchema: JSONSchemaType<SessionParams> = {
+export const SessionParamsSchema = schema<SessionParams>({
   type: 'object',
   properties: {
     sid: { type: 'string', minLength: 1 },
   },
   required: ['sid'],
   additionalProperties: false,
-}
+})
 
-export const ItemParamsSchema: JSONSchemaType<ItemParams> = {
+export const ItemParamsSchema = schema<ItemParams>({
   type: 'object',
   properties: {
     sid: { type: 'string', minLength: 1 },
@@ -27,4 +27,4 @@ export const ItemParamsSchema: JSONSchemaType<ItemParams> = {
   },
   required: ['sid', 'id'],
   additionalProperties: false,
-}
+})

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

@@ -1,11 +1,10 @@
-import { BASE, entrypoint, entrypoints as baseEntrypoints, frontend, handler, HOME, route } from '@owlmeans/web-panel'
+import { BASE, bind, entrypoint, entrypoints as baseEntrypoints, frontend, handler, HOME, route } from '@owlmeans/web-panel'
 import { sharedEntrypoints } from '__APP_SLUG__-common'
 import { MainLayout } from './layout/main.js'
 import { HomeScreen } from './screens/home.js'
 
-// Backend entrypoints arrive as declarations only — `elevate(entrypoints, alias)` (from
-// '@owlmeans/web-panel') makes one callable here without giving it a component.
-const entrypoints = [...baseEntrypoints, ...sharedEntrypoints]
+// Backend protocol declarations are materialized locally so each can be called from the browser.
+const entrypoints = [...baseEntrypoints, ...sharedEntrypoints.map(protocol => bind(protocol))]
 
 // Frontend layout + screens. BASE renders the shared layout; HOME is its default child.
 entrypoints.push(entrypoint(route(BASE, '/', frontend()), handler(MainLayout)))

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

@@ -1,22 +1,16 @@
-import { BASE, elevate, entrypoint, entrypoints as baseEntrypoints, frontend, handler, HOME, route } from '@owlmeans/web-panel'
-import { session, sessionEntrypoints, web } from '__APP_SLUG__-common'
+import { bindAll, bindScreen, entrypoints as baseEntrypoints, handler } from '@owlmeans/web-panel'
+import { session, 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]
+const entrypoints = [...baseEntrypoints, ...bindAll(session)]
 
-// 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)))
+// Frontend protocol declarations bind to renderers in the web project.
+entrypoints.push(bindScreen(web.base, handler(MainLayout)))
+entrypoints.push(bindScreen(web.home, handler(HomeScreen)))
+entrypoints.push(bindScreen(web.session, handler(SessionScreen)))
+entrypoints.push(bindScreen(web.about, handler(AboutScreen)))
 
 export const appEntrypoints = entrypoints

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

@@ -1,5 +1,4 @@
 import { useEffect, useState, type FC } from 'react'
-import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
 import { useStoreList } from '@owlmeans/client'
 import { session, type SessionItem } from '__APP_SLUG__-common'
 import { SESSION_STATE, useContext } from '../context.js'
@@ -39,7 +38,7 @@ export const SessionScreen: FC = () => {
   // leave the store too, and one write wakes the subscribers once instead of once per record.
   const load = async () => {
     const data = await ctx
-      .entrypoint<ClientEntrypoint<SessionItem[]>>(session.list)
+      .entrypoint(session.list)
       .call({ params: { sid } })
     await store.replace(data ?? [])
   }
@@ -51,7 +50,7 @@ export const SessionScreen: FC = () => {
     setBusy(true)
     try {
       const item = await ctx
-        .entrypoint<ClientEntrypoint<SessionItem>>(session.add)
+        .entrypoint(session.add)
         .call({ params: { sid }, body: { text } })
       setText('')
       if (item != null) {
@@ -64,7 +63,7 @@ export const SessionScreen: FC = () => {
 
   const remove = async (id: string) => {
     await ctx
-      .entrypoint<ClientEntrypoint<{ removed: boolean }>>(session.remove)
+      .entrypoint(session.remove)
       .call({ params: { sid, id } })
     await store.delete(id)
   }