@owlmeans/create-app 0.1.18-rc.58 → 0.1.18-rc.59

package/README.md

@@ -9,7 +9,7 @@ bun create @owlmeans/app my-app
 # or
 yarn create @owlmeans/app my-app
 # or
-npx @owlmeans/create-app@^0.1.18-rc.58 my-app
+npx @owlmeans/create-app@^0.1.18-rc.59 my-app
 ```
 
 ## What it generates

package/build/consts.local.d.ts

@@ -1,5 +1,5 @@
 import type { PackageManager } from './types.js';
-export declare const HELP = "@owlmeans/create-app \u2014 scaffold a fullstack OwlMeans Common app\n\nUsage:\n  npm create @owlmeans/app@latest <dir> [options]\n  bun create @owlmeans/app <dir> [options]\n  yarn create @owlmeans/app <dir> [options]\n  npx @owlmeans/create-app@^0.1.18-rc.58 <dir> [options]\n\nGenerates three workspaces (common + api + web) with shadcn UI navigation and\nlayout, no authentication, and a session-scoped in-memory resource on the\nbackend. With --bare the demo is left out and only the working shell remains.\nAgent skills are deployed into the project by default.\n\nOptions:\n  --name <name>       human-readable app name (default: derived from <dir>)\n  --slug <slug>       package slug (default: derived from <dir>)\n  --lang <code>       language of the generated UI text (default: en)\n  --description <t>   one-line project description for the generated docs\n  --bare              scaffold the shell only \u2014 no example/demo code\n  --pm <bun|npm|yarn> package manager (default: bun)\n  --no-install        do not install dependencies\n  --no-skills         do not deploy agent skills via @owlmeans/agent-skills\n  --no-git            do not run \"git init\"\n  --yes, -y           proceed without prompts / into a non-empty directory\n  --help, -h          show this help\n";
+export declare const HELP = "@owlmeans/create-app \u2014 scaffold a fullstack OwlMeans Common app\n\nUsage:\n  npm create @owlmeans/app@latest <dir> [options]\n  bun create @owlmeans/app <dir> [options]\n  yarn create @owlmeans/app <dir> [options]\n  npx @owlmeans/create-app@^0.1.18-rc.59 <dir> [options]\n\nGenerates three workspaces (common + api + web) with shadcn UI navigation and\nlayout, no authentication, and a session-scoped in-memory resource on the\nbackend. With --bare the demo is left out and only the working shell remains.\nAgent skills are deployed into the project by default.\n\nOptions:\n  --name <name>       human-readable app name (default: derived from <dir>)\n  --slug <slug>       package slug (default: derived from <dir>)\n  --lang <code>       language of the generated UI text (default: en)\n  --description <t>   one-line project description for the generated docs\n  --bare              scaffold the shell only \u2014 no example/demo code\n  --pm <bun|npm|yarn> package manager (default: bun)\n  --no-install        do not install dependencies\n  --no-skills         do not deploy agent skills via @owlmeans/agent-skills\n  --no-git            do not run \"git init\"\n  --yes, -y           proceed without prompts / into a non-empty directory\n  --help, -h          show this help\n";
 export declare const PMS: PackageManager[];
 /** Dotfiles/dirs are shipped with an underscore prefix so npm does not strip them from the tarball. */
 export declare const DOTFILE_RENAMES: Record<string, string>;

package/build/consts.local.js

@@ -5,7 +5,7 @@ Usage:
   npm create @owlmeans/app@latest <dir> [options]
   bun create @owlmeans/app <dir> [options]
   yarn create @owlmeans/app <dir> [options]
-  npx @owlmeans/create-app@^0.1.18-rc.58 <dir> [options]
+  npx @owlmeans/create-app@^0.1.18-rc.59 <dir> [options]
 
 Generates three workspaces (common + api + web) with shadcn UI navigation and
 layout, no authentication, and a session-scoped in-memory resource on the

package/build/run.js

@@ -50,7 +50,7 @@ export const run = async (args) => {
         log(args.install
             ? '\nDeploying agent skills via @owlmeans/agent-skills…'
             : '\nDeploying harness guidance via @owlmeans/agent-skills (general skills only — re-run'
-                + '\n`npx @owlmeans/agent-skills@^0.1.18-rc.49` after installing to add the package-specific ones)…');
+                + '\n`npx @owlmeans/agent-skills@^0.1.18-rc.50` after installing to add the package-specific ones)…');
         try {
             const result = await installSkills({
                 dir: dest,
@@ -62,7 +62,7 @@ export const run = async (args) => {
                 help: false,
             });
             if (result.code !== 0) {
-                process.stderr.write(`  agent-skills exited with code ${result.code} — you can re-run \`npx @owlmeans/agent-skills@^0.1.18-rc.49\` later.\n`);
+                process.stderr.write(`  agent-skills exited with code ${result.code} — you can re-run \`npx @owlmeans/agent-skills@^0.1.18-rc.50\` later.\n`);
             }
         }
         catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/create-app",
-  "version": "0.1.18-rc.58",
+  "version": "0.1.18-rc.59",
   "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.49"
+    "@owlmeans/agent-skills": "^0.1.18-rc.50"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",

package/template/AGENTS.md

@@ -114,7 +114,7 @@ from the installed `@owlmeans/*` packages. Agents load a skill by topic, or you
 explicitly. Copilot and Codex read `.agents/skills/` directly; Claude Code reads the generated
 symlinks in `.claude/skills/` (see "Claude Code" below).
 
-- After adding or updating any `@owlmeans/*` dependency, run `npx @owlmeans/agent-skills@^0.1.18-rc.49` to refresh
+- After adding or updating any `@owlmeans/*` dependency, run `npx @owlmeans/agent-skills@^0.1.18-rc.50` to refresh
   the deployed skills.
 - `/logging` — before adding any log line, catch block or `console` call (mechanics: `/log`).
 - Deployed files carry an `AUTO-GENERATED` banner and are refreshed in place — never hand-edit them.

package/template/README.bare.md

@@ -66,5 +66,5 @@ them; write your own guidance as separate, un-bannered files. Refresh after addi
 `@owlmeans/*` packages:
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.49
+npx @owlmeans/agent-skills@^0.1.18-rc.50
 ```

package/template/_agents/skills/owlmeans-code-structure/SKILL.md

@@ -140,16 +140,21 @@ scripts, error classes and schema files.
 Applications the viable agent generates follow the same rules, in these fixed shapes:
 
 - **Domain model per entity.** `backend/src/models/<entity>/types.ts` declares
-  `interface <Entity>Model` first; `models/<entity>/<entity>.ts` exports only
-  `make<Entity>Model = (ctx: Context): <Entity>Model => { const op = async (actor: Actor, …) => …; return { op, … } }`.
+  `interface <Base>Model` first; `models/<entity>/<base>.ts` exports only
+  `make<Base>Model = (ctx: Context): <Base>Model => { const op = async (actor: Actor, …) => …; return { op, … } }`.
   It is built where it is used — `await makeTaskModel(ctx).complete(actorOf(request), id)` — and is
   never registered as a context service. Its member names are the endpoint keys of the entity.
 - **Handlers and job processors**: one plain exported function per file
-  (`api/src/app/<entity>/<action>.ts`, `worker/src/jobs/<job>.ts`); a handler's body is one call into
-  the model.
-- **Seed helpers are objects**: `actorOf(request): Actor` with `actor.inOrganization(…)`,
-  `actor.assertOrganization(…)`, `actor.grantedIds(…)`, `actor.organizationScope(…)`; the
-  record-owner, visit, planning-access, landing hand-off and llm helpers likewise.
+  (`api/src/app/<entity>/<action>.ts` beside a GENERATED `index.ts` barrel, `worker/src/jobs/<job>.ts`);
+  a handler's body is one call into the model.
+- **Seed helpers are objects** whose members keep the old function names:
+  `actorOf(request): Actor` with `actor.inOrganization(…)`, `actor.assertOrganization(…)`,
+  `actor.grantedIds(…)`, `actor.organizationScope(…)`; `recordOwnerOf(request)`, `visitOf(request)`,
+  `planningAccessOf(request, ctx)`, `landingHandoff`, `visitKey`. Their types live in the module's
+  same-named folder (`lib/actor/types.ts`); the old free functions stay as
+  `@deprecated generated-app:factory-objects` wrappers so a project generated before still compiles.
+- A model module generated before this shape keeps its plain functions: its callers import them by
+  name, so it is extended in that shape and never converted in place.
 - **Resources** keep their maker and their `xResource(ctx)` accessor; the resource's interface lives
   in `resources/<entity>/types.ts`.
 - Shared types in `common` are interfaces.

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

@@ -47,7 +47,7 @@ How you research the repo depends on whether `@owlmeans/*` is linked locally:
   **https://github.com/owlmeans/common** — `tree.md` and package READMEs — to find the right package.
 
 This is the same dev-linked detection `@owlmeans/agent-skills` uses (see its `detectLinked`). After
-adding an `@owlmeans/*` dependency, run `npx @owlmeans/agent-skills@^0.1.18-rc.49` to deploy its
+adding an `@owlmeans/*` dependency, run `npx @owlmeans/agent-skills@^0.1.18-rc.50` to deploy its
 skill. Prefer an `@owlmeans/*` package over a third-party library or bespoke code whenever one fits.
 
 ### Never add an OwlMeans dependency without an explicit range

package/template/_bare.json

@@ -4,6 +4,7 @@
     "sources/common/src/schemas.ts",
     "sources/api/src/consts.ts",
     "sources/api/src/app",
+    "sources/api/src/models",
     "sources/web/src/screens/about.tsx",
     "sources/web/src/screens/session.tsx"
   ],

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

@@ -1,21 +1,9 @@
-import { randomUUID } from 'node:crypto'
 import { handlers } from '@owlmeans/server-app'
-import { session, type SessionItem } from '__APP_SLUG__-common'
-import { SESSION_ITEMS } from '../../consts.js'
+import { session } from '__APP_SLUG__-common'
+import { makeSessionModel } from '../../models/session.js'
 import type { Context } from '../../types.js'
 
 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(),
-    sessionId: sid,
-    text: payload.text,
-    createdAt: new Date().toISOString(),
-  }
-
-  return await resource.create(item)
-})
+export const add = handle.body(session.add, async (payload, context, request) =>
+  await makeSessionModel(context, request.params.sid).add(payload.text))

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

@@ -1,18 +1,9 @@
 import { handlers } from '@owlmeans/server-app'
-import { session, type SessionItem } from '__APP_SLUG__-common'
-import { SESSION_ITEMS } from '../../consts.js'
+import { session } from '__APP_SLUG__-common'
+import { makeSessionModel } from '../../models/session.js'
 import type { Context } from '../../types.js'
 
 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(
-    { sessionId: params.sid },
-    { sort: [{ field: 'createdAt', order: 'desc' }] }
-  )
-
-  return items
-})
+export const list = handle.params(session.list, async (params, context) =>
+  await makeSessionModel(context, params.sid).list())

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

@@ -1,19 +1,9 @@
 import { handlers } from '@owlmeans/server-app'
-import { session, type SessionItem } from '__APP_SLUG__-common'
-import { SESSION_ITEMS } from '../../consts.js'
+import { session } from '__APP_SLUG__-common'
+import { makeSessionModel } from '../../models/session.js'
 import type { Context } from '../../types.js'
 
 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.
-  if (existing == null || existing.sessionId !== params.sid) {
-    return { removed: false }
-  }
-
-  await resource.delete(params.id)
-  return { removed: true }
-})
+export const remove = handle.params(session.remove, async (params, context) =>
+  await makeSessionModel(context, params.sid).remove(params.id))

package/template/sources/api/src/models/session/types.ts

@@ -0,0 +1,14 @@
+import type { SessionItem } from '__APP_SLUG__-common'
+
+/**
+ * The items of ONE browser session. The session id is bound when the model is built, so no
+ * member can reach another session's items; the member names are the session endpoints' keys.
+ */
+export interface SessionModel {
+  /** This session's items, newest first. */
+  list: () => Promise<SessionItem[]>
+  /** Store a new item under this session. */
+  add: (text: string) => Promise<SessionItem>
+  /** Remove an item — only when it belongs to this session. */
+  remove: (id: string) => Promise<{ removed: boolean }>
+}

package/template/sources/api/src/models/session.ts

@@ -0,0 +1,43 @@
+import { randomUUID } from 'node:crypto'
+import type { SessionItem } from '__APP_SLUG__-common'
+import { SESSION_ITEMS } from '../consts.js'
+import type { Context } from '../types.js'
+import type { SessionModel } from './session/types.js'
+
+/**
+ * The session domain, bound to the context that holds its resource and to the session it serves.
+ * Built where it is used — `makeSessionModel(context, sid).list()` — never stored.
+ */
+export const makeSessionModel = (context: Context, sid: string): SessionModel => {
+  const resource = context.getStaticResource<SessionItem>(SESSION_ITEMS)
+
+  const list: SessionModel['list'] = async () => {
+    // The resource answers the whole question — this session's items, newest first.
+    const { items } = await resource.list(
+      { sessionId: sid },
+      { sort: [{ field: 'createdAt', order: 'desc' }] }
+    )
+
+    return items
+  }
+
+  const add: SessionModel['add'] = async text => await resource.create({
+    id: randomUUID(),
+    sessionId: sid,
+    text,
+    createdAt: new Date().toISOString(),
+  })
+
+  const remove: SessionModel['remove'] = async id => {
+    const existing = await resource.load(id)
+    // Only remove the item if it belongs to this session.
+    if (existing == null || existing.sessionId !== sid) {
+      return { removed: false }
+    }
+
+    await resource.delete(id)
+    return { removed: true }
+  }
+
+  return { list, add, remove }
+}

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

@@ -3,6 +3,9 @@ import { type PanelNavLink, HOME } from '@owlmeans/web-panel'
 /** The alias the session items are stored under. Screens address the store by it, never by path. */
 export const SESSION_STATE = 'session-items'
 
+/** The `localStorage` key that keeps this browser's session id across reloads. */
+export const SESSION_ID_KEY = '__APP_SLUG__-sid'
+
 // The platform/owner credit — "Powered by OwlMeans" and the copyright the platform delivers — is
 // rendered by the shell itself (`NavLayout`'s `Footer`) and is never a footer link: an app link
 // list is places IN the app, and the credit is not one of those.

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

@@ -2,18 +2,16 @@ import { useEffect, useState, type FC } from 'react'
 import { useStoreList } from '@owlmeans/client'
 import { session, type SessionItem } from '__APP_SLUG__-common'
 import { useContext } from '../context.js'
-import { SESSION_STATE } from '../consts.js'
+import { SESSION_ID_KEY, SESSION_STATE } from '../consts.js'
 import { Button } from '@/components/ui/button'
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
 import { Input } from '@/components/ui/input'
 
-const SID_KEY = '__APP_SLUG__-sid'
-
 const sessionId = (): string => {
-  let sid = localStorage.getItem(SID_KEY)
+  let sid = localStorage.getItem(SESSION_ID_KEY)
   if (sid == null) {
     sid = crypto.randomUUID()
-    localStorage.setItem(SID_KEY, sid)
+    localStorage.setItem(SESSION_ID_KEY, sid)
   }
   return sid
 }