@owlmeans/create-app 0.1.18-rc.6 → 0.1.18-rc.61

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (115) hide show
  1. package/README.md +49 -5
  2. package/build/args/types.d.ts +9 -0
  3. package/build/args/types.d.ts.map +1 -0
  4. package/build/args/types.js +2 -0
  5. package/build/args/types.js.map +1 -0
  6. package/build/args.d.ts +3 -20
  7. package/build/args.d.ts.map +1 -1
  8. package/build/args.js +121 -88
  9. package/build/args.js.map +1 -1
  10. package/build/bin.js +3 -3
  11. package/build/bin.js.map +1 -1
  12. package/build/consts.d.ts +6 -0
  13. package/build/consts.d.ts.map +1 -0
  14. package/build/consts.js +6 -0
  15. package/build/consts.js.map +1 -0
  16. package/build/consts.local.d.ts +12 -0
  17. package/build/consts.local.d.ts.map +1 -0
  18. package/build/consts.local.js +49 -0
  19. package/build/consts.local.js.map +1 -0
  20. package/build/index.d.ts +11 -4
  21. package/build/index.d.ts.map +1 -1
  22. package/build/index.js +5 -2
  23. package/build/index.js.map +1 -1
  24. package/build/naming/types.d.ts +14 -0
  25. package/build/naming/types.d.ts.map +1 -0
  26. package/build/naming/types.js +2 -0
  27. package/build/naming/types.js.map +1 -0
  28. package/build/naming.d.ts +4 -0
  29. package/build/naming.d.ts.map +1 -0
  30. package/build/naming.js +18 -0
  31. package/build/naming.js.map +1 -0
  32. package/build/run.d.ts +1 -1
  33. package/build/run.d.ts.map +1 -1
  34. package/build/run.js +23 -17
  35. package/build/run.js.map +1 -1
  36. package/build/scaffold.d.ts +8 -0
  37. package/build/scaffold.d.ts.map +1 -0
  38. package/build/scaffold.js +19 -0
  39. package/build/scaffold.js.map +1 -0
  40. package/build/template/types.d.ts +16 -0
  41. package/build/template/types.d.ts.map +1 -0
  42. package/build/template/types.js +2 -0
  43. package/build/template/types.js.map +1 -0
  44. package/build/template.d.ts +3 -16
  45. package/build/template.d.ts.map +1 -1
  46. package/build/template.js +69 -52
  47. package/build/template.js.map +1 -1
  48. package/build/types.d.ts +61 -0
  49. package/build/types.d.ts.map +1 -0
  50. package/build/types.js +2 -0
  51. package/build/types.js.map +1 -0
  52. package/package.json +5 -4
  53. package/template/AGENTS.md +61 -2
  54. package/template/README.bare.md +70 -0
  55. package/template/README.md +9 -60
  56. package/template/_agents/scripts/link-skills.sh +327 -15
  57. package/template/_agents/skills/agent-memory/SKILL.md +12 -11
  58. package/template/_agents/skills/getting-started/SKILL.md +38 -79
  59. package/template/_agents/skills/logging/SKILL.md +41 -0
  60. package/template/_agents/skills/memory-promotion/SKILL.md +10 -4
  61. package/template/_agents/skills/memory-recompact/SKILL.md +15 -14
  62. package/template/_agents/skills/owlmeans-code-structure/SKILL.md +182 -0
  63. package/template/_agents/skills/reuse-code/SKILL.md +56 -10
  64. package/template/_agents/skills/self-education/SKILL.md +25 -5
  65. package/template/_agents/skills/skill-authoring/SKILL.md +78 -12
  66. package/template/_bare.json +24 -0
  67. package/template/_gitignore +8 -0
  68. package/template/bunfig.toml +2 -0
  69. package/template/package.json +3 -2
  70. package/template/sources/api/package.json +5 -4
  71. package/template/sources/api/src/app/session/add.ts +6 -17
  72. package/template/sources/api/src/app/session/list.ts +6 -12
  73. package/template/sources/api/src/app/session/remove.ts +6 -15
  74. package/template/sources/api/src/config.ts +7 -0
  75. package/template/sources/api/src/context.bare.ts +11 -0
  76. package/template/sources/api/src/entrypoints.bare.ts +4 -0
  77. package/template/sources/api/src/entrypoints.ts +13 -0
  78. package/template/sources/api/src/index.ts +8 -2
  79. package/template/sources/api/src/models/session/types.ts +14 -0
  80. package/template/sources/api/src/models/session.ts +43 -0
  81. package/template/sources/api/src/types.bare.ts +5 -0
  82. package/template/sources/common/package.json +8 -8
  83. package/template/sources/common/src/config.ts +2 -1
  84. package/template/sources/common/src/consts.bare.ts +8 -0
  85. package/template/sources/common/src/consts.ts +0 -13
  86. package/template/sources/common/src/entrypoints.bare.ts +14 -0
  87. package/template/sources/common/src/entrypoints.ts +60 -0
  88. package/template/sources/common/src/index.bare.ts +3 -0
  89. package/template/sources/common/src/index.ts +1 -1
  90. package/template/sources/common/src/schemas.ts +7 -7
  91. package/template/sources/web/index.html +3 -1
  92. package/template/sources/web/package.json +33 -30
  93. package/template/sources/web/src/components/ui/dropdown-menu.tsx +257 -0
  94. package/template/sources/web/src/components/ui/navigation-menu.tsx +169 -0
  95. package/template/sources/web/src/config.ts +8 -0
  96. package/template/sources/web/src/consts.ts +14 -0
  97. package/template/sources/web/src/context.bare.ts +13 -0
  98. package/template/sources/web/src/context.ts +12 -2
  99. package/template/sources/web/src/entrypoints.bare.ts +13 -0
  100. package/template/sources/web/src/entrypoints.ts +16 -0
  101. package/template/sources/web/src/index.css +7 -0
  102. package/template/sources/web/src/index.tsx +2 -2
  103. package/template/sources/web/src/layout/main.tsx +17 -19
  104. package/template/sources/web/src/nav.bare.ts +23 -0
  105. package/template/sources/web/src/nav.ts +23 -0
  106. package/template/sources/web/src/screens/about.tsx +19 -0
  107. package/template/sources/web/src/screens/home.bare.tsx +17 -0
  108. package/template/sources/web/src/screens/session.tsx +30 -17
  109. package/template/sources/web/src/vite-env.d.ts +8 -0
  110. package/template/sources/web/vite.config.ts +3 -2
  111. package/template/CLAUDE.md +0 -13
  112. package/template/sources/api/src/modules.ts +0 -11
  113. package/template/sources/common/src/modules.ts +0 -26
  114. package/template/sources/web/src/components/nav/main.tsx +0 -15
  115. package/template/sources/web/src/modules.ts +0 -20
@@ -9,13 +9,26 @@ metadata:
9
9
 
10
10
  # Authoring agent guidance (skills)
11
11
 
12
- OwlMeans projects carry agent guidance in two places, and only two:
12
+ An OwlMeans project carries agent guidance in up to three places:
13
13
 
14
14
  | What | Where | Loaded |
15
15
  |---|---|---|
16
16
  | Always-on project context | `AGENTS.md` at the repo root | every session |
17
+ | Always-on policy, kept out of `AGENTS.md` | `.agents/rules/<topic>.md`, pulled in from `AGENTS.md` by an `@.agents/rules/<topic>.md` import line | every session |
17
18
  | Topic guidance | `.agents/skills/<name>/SKILL.md` | on demand, by topic or `/<name>` |
18
19
 
20
+ The middle tier is optional and belongs to a repo that has grown standing policy of its own. A
21
+ project scaffolded by `@owlmeans/create-app` starts without a `.agents/rules/` directory: its
22
+ generated `AGENTS.md` states the git policy inline and points at the seeded `git` skill for the
23
+ rest. Follow the layout the project already has — add a rules file only where `AGENTS.md` already
24
+ imports one.
25
+
26
+ **Rule or skill?** A rule is policy that has to hold whether or not anyone thought to load
27
+ anything — the git workflow is the standing example, whether a repo keeps it as
28
+ `.agents/rules/git.md` or inline in `AGENTS.md`. A skill is guidance for a task, loaded when that
29
+ task comes up. If it only matters while you are doing X, write a skill; if breaking it is wrong at any moment, state it in a line or two where `AGENTS.md` loads it every
30
+ session, and keep its detail in a skill (§ What may enter AGENTS.md).
31
+
19
32
  `.agents/skills/` is the [Agent Skills](https://agentskills.io) standard location: GitHub Copilot
20
33
  and Codex discover it natively. Claude Code reads skills only from `.claude/skills/`, so each skill
21
34
  is bridged there by a generated symlink — see "Refresh the Claude Code links" below. **Write a skill
@@ -38,20 +51,43 @@ once; never author a per-agent copy** (`.github/instructions/*.instructions.md`,
38
51
  name: my-skill # REQUIRED, must equal the directory name (lowercase, hyphens, ≤64 chars)
39
52
  description: What it does and WHEN to use it. # REQUIRED, ≤1024 chars — the auto-invocation signal
40
53
  user-invocable: true # false = background knowledge only, hidden from the / menu
41
- allowed-tools: Bash(bun *) Read # optional — space-separated; tools usable without per-call approval
54
+ allowed-tools: Bash(bun *), Read # optional — COMMA-separated; tools usable without per-call approval
42
55
  metadata: # optional — anything non-standard goes here
43
56
  scope: general
44
57
  ---
45
58
  ```
46
59
 
60
+ The `name` is not free: it is the key every store is keyed by, and a LOCAL skill always wins over
61
+ one that arrives from a dependency. Naming a skill after a package you depend on therefore hides
62
+ that package's own guidance completely, and the installer reports the file as a conflict on every
63
+ run. Give a skill about your own use of `@owlmeans/payment` a name of its own — `billing`, or your
64
+ product's name with a suffix — never `payment`.
65
+
66
+ **Never name a skill after a Claude Code built-in slash command.** Claude Code resolves `/<name>` to
67
+ a skill before the built-in command of the same name, so a skill called `context`, `config`,
68
+ `memory` or `review` makes that command unreachable wherever the skill is installed or linked, and
69
+ nothing reports it. The same holds for a command's aliases (`/settings` is `/config`, `/cost` is
70
+ `/usage`) and for the skills Claude Code bundles (`/loop`, `/simplify`); type `/` in a Claude Code
71
+ session to see every taken name. OwlMeans package skills follow this too: the guidance for
72
+ `@owlmeans/context` and `@owlmeans/config` ships as `owlmeans-context` and `owlmeans-config`.
73
+
47
74
  The `description` is the most important field: every agent uses it to decide when to load the
48
75
  skill, so state both the topic and the trigger ("Use when …"). Keep it under 1024 characters —
49
- Copilot rejects longer ones.
50
-
51
- Only the fields above (plus `license` and `compatibility`) are portable. Anything else — including
52
- this monorepo's `scope: general` routing marker — belongs under `metadata:`, so a skill stays valid
53
- in every agent that reads it. Claude Code additionally understands `disable-model-invocation`,
54
- `argument-hint` and `context: fork`; use them only when the skill genuinely needs them.
76
+ Copilot rejects longer ones. It is YAML, so a value containing `: ` (colon-space) has to be quoted
77
+ or the file stops parsing and the skill silently disappears from every agent.
78
+
79
+ `allowed-tools` is parsed as a list split on commas, newlines and YAML `-` bullets — never on
80
+ plain spaces. `Bash(bun *) Read` is read as one tool named `Bash(bun *) Read`, which matches
81
+ nothing; write `Bash(bun *), Read`.
82
+
83
+ Six keys are what the Agent Skills frontmatter parser in `@owlmeans/agent-skills` stores:
84
+ `name`, `description`, `license`, `compatibility`, `allowed-tools` and nested `metadata`.
85
+ Project-specific keys — including the OwlMeans `scope: general` routing marker, which sends a skill
86
+ to the installer bundle rather than to one package — belong under `metadata:`, so a skill stays
87
+ valid in every agent that reads it. The invocation switches sit outside what that parser stores and
88
+ are written at the top level alongside it: `user-invocable` (`false` hides a skill from the `/`
89
+ menu, marking it background knowledge), plus `disable-model-invocation` and `argument-hint`, which
90
+ Claude Code understands. Set any of them only when the skill needs it.
55
91
 
56
92
  ## Refresh the Claude Code links
57
93
 
@@ -61,9 +97,23 @@ After creating, renaming, or deleting a skill, run:
61
97
  sh .agents/scripts/link-skills.sh
62
98
  ```
63
99
 
64
- It creates `.claude/skills/<name>` → `../../.agents/skills/<name>` for every skill and prunes links
65
- whose skill is gone. The links are gitignored and are recreated at session start, but a skill added
66
- mid-session is invisible to Claude Code until the script runs.
100
+ It creates `.claude/skills/<name>` → `../../.agents/skills/<name>` for every local skill and prunes
101
+ links whose skill is gone. The links are gitignored and are recreated at session start (a committed
102
+ `SessionStart` hook, and on every install where the project declares a root `prepare` script that
103
+ calls it), but a skill added mid-session is invisible to Claude Code until the script runs.
104
+
105
+ The same script also brings in the skills of everything this project depends on, from whichever of
106
+ two sources applies. In a linked checkout — a repo whose root `package.json` lists an upstream
107
+ repo's packages as workspace entries — it resolves those upstream repos first, recursing into each
108
+ one's own manifest up to four levels, and links the skills from the upstream's own
109
+ `.agents/skills/`. A project that declares no such linked upstream falls back to what a plain npm
110
+ install gives it: the read-only `agent-meta/skills/` copies shipped inside each installed
111
+ `@owlmeans/*` package. Either way the links land in `.agents/linked-skills/<name>` (Copilot, Codex)
112
+ and `.claude/skills/<name>` (Claude Code), with a generated `.agents/linked-skills/INDEX.md` listing
113
+ skill, origin and description. Load one by name exactly like a local skill. A local skill of the
114
+ same name always wins, and a nearer dependency wins over a farther one. The whole
115
+ `.agents/linked-skills/` directory is generated and git-ignored — never edit or commit it, and never
116
+ edit an `agent-meta/` copy: fix the skill in the package that ships it.
67
117
 
68
118
  ## Skill vs memory
69
119
 
@@ -80,10 +130,26 @@ Never paste memory text into a skill. Memory content enters guidance only as a r
80
130
  rule — trigger, step, and the failure it prevents, with dates, phase/status markers, versions and
81
131
  incident narrative stripped (`memory-promotion` → Distillation).
82
132
 
133
+ ## What may enter AGENTS.md
134
+
135
+ `AGENTS.md` — with every file it `@`-imports and `.agents/memory/MEMORY.md` — is loaded in full in
136
+ every session, so it has a budget: **≤ 40 000 chars**, checked by `sh .agents/scripts/agents-size.sh`
137
+ from the repo root where the repo carries it. A line enters it only as:
138
+
139
+ 1. a mandatory rule that must hold before any skill is loaded (git, reporting, environments,
140
+ naming, code structure) — stated in one or two lines, with the detail in a skill;
141
+ 2. one line of the package map or the command list;
142
+ 3. one line of the skills index: `` - `/name` — when to load it ``, ≤ 160 chars.
143
+
144
+ Everything else is loaded on demand: a subsystem's rules, contracts and failure fingerprints go to
145
+ the skill that governs it, and the outage that taught them to `.agents/memory/`. Never paraphrase a
146
+ skill's `description:` into the index — skills self-describe. A change that would push the file over
147
+ budget shortens or moves an existing line in the same change.
148
+
83
149
  ## After adding a skill
84
150
 
85
151
  1. If it replaces an ad-hoc `.agents/<topic>.md`, remove that file.
86
152
  2. If it distilled memory content into rules, shrink the source `.agents/memory/` node to a
87
153
  pointer line (`memory-promotion`) — the memory index does not list skills.
88
- 3. Reference it from `AGENTS.md` if it should be discoverable every session.
154
+ 3. Add one line to the skills index in `AGENTS.md` (`/name` — when to load it, ≤ 160 chars) — never a paragraph (§ What may enter AGENTS.md).
89
155
  4. Run `sh .agents/scripts/link-skills.sh`.
@@ -0,0 +1,24 @@
1
+ {
2
+ "remove": [
3
+ "sources/common/src/types.ts",
4
+ "sources/common/src/schemas.ts",
5
+ "sources/api/src/consts.ts",
6
+ "sources/api/src/app",
7
+ "sources/api/src/models",
8
+ "sources/web/src/screens/about.tsx",
9
+ "sources/web/src/screens/session.tsx"
10
+ ],
11
+ "overrides": {
12
+ "README.md": "README.bare.md",
13
+ "sources/common/src/consts.ts": "sources/common/src/consts.bare.ts",
14
+ "sources/common/src/entrypoints.ts": "sources/common/src/entrypoints.bare.ts",
15
+ "sources/common/src/index.ts": "sources/common/src/index.bare.ts",
16
+ "sources/api/src/context.ts": "sources/api/src/context.bare.ts",
17
+ "sources/api/src/entrypoints.ts": "sources/api/src/entrypoints.bare.ts",
18
+ "sources/api/src/types.ts": "sources/api/src/types.bare.ts",
19
+ "sources/web/src/context.ts": "sources/web/src/context.bare.ts",
20
+ "sources/web/src/entrypoints.ts": "sources/web/src/entrypoints.bare.ts",
21
+ "sources/web/src/nav.ts": "sources/web/src/nav.bare.ts",
22
+ "sources/web/src/screens/home.tsx": "sources/web/src/screens/home.bare.tsx"
23
+ }
24
+ }
@@ -6,6 +6,14 @@ dist
6
6
  bun.lock
7
7
  bun.lockb
8
8
 
9
+ # Developer-local environment (LOG_LEVEL, VITE_LOG_LEVEL, …)
10
+ .env
11
+ .env.local
12
+ .env.*.local
13
+
9
14
  # Generated Claude Code skill symlinks (canonical skills live in .agents/skills/)
10
15
  .claude/skills/*
11
16
  !.claude/skills/.gitkeep
17
+
18
+ # Skills linked from upstream repos (generated by .agents/scripts/link-skills.sh)
19
+ .agents/linked-skills/
@@ -0,0 +1,2 @@
1
+ [install]
2
+ linker = "hoisted"
@@ -3,14 +3,15 @@
3
3
  "version": "0.1.0",
4
4
  "private": true,
5
5
  "type": "module",
6
- "packageManager": "bun@1.3.14",
6
+ "packageManager": "bun@1.4.2",
7
7
  "workspaces": [
8
8
  "sources/*"
9
9
  ],
10
10
  "scripts": {
11
11
  "dev": "bun run --filter './sources/common' build && bun run --filter './sources/*' --parallel dev",
12
12
  "build": "bun run --filter './sources/*' build",
13
- "typecheck": "bun run --filter './sources/*' typecheck"
13
+ "typecheck": "bun run --filter './sources/*' typecheck",
14
+ "prepare": "sh -c 'test -f .agents/scripts/link-skills.sh && sh .agents/scripts/link-skills.sh || true'"
14
15
  },
15
16
  "devDependencies": {
16
17
  "nodemon": "^3.1.14"
@@ -11,13 +11,14 @@
11
11
  "typecheck": "tsc -b"
12
12
  },
13
13
  "dependencies": {
14
- "@owlmeans/server-app": "^0.1.16",
15
- "@owlmeans/static-resource": "^0.1.16",
14
+ "@owlmeans/log": "^0.1.18-rc.3",
15
+ "@owlmeans/server-app": "^0.1.18-rc.54",
16
+ "@owlmeans/static-resource": "^0.1.18-rc.39",
16
17
  "__APP_SLUG__-common": "workspace:^"
17
18
  },
18
19
  "devDependencies": {
19
- "@owlmeans/dep-config": "^0.1.16",
20
- "@types/node": "^24.10.1",
20
+ "@owlmeans/dep-config": "^0.1.18-rc.6",
21
+ "@types/node": "^26.6.4",
21
22
  "typescript": "^7.0.2"
22
23
  }
23
24
  }
@@ -1,20 +1,9 @@
1
- import { randomUUID } from 'node:crypto'
2
- import { handleBody } from '@owlmeans/server-app'
3
- import type { AddItemPayload, SessionItem, SessionParams } from '__APP_SLUG__-common'
4
- import { SESSION_ITEMS } from '../../consts.js'
1
+ import { handlers } from '@owlmeans/server-app'
2
+ import { session } from '__APP_SLUG__-common'
3
+ import { makeSessionModel } from '../../models/session.js'
5
4
  import type { Context } from '../../types.js'
6
5
 
7
- export const add = handleBody<AddItemPayload>(async (payload, context, req) => {
8
- const ctx = context as Context
9
- const { sid } = req.params as SessionParams
10
- const resource = ctx.getStaticResource<SessionItem>(SESSION_ITEMS)
6
+ const handle = handlers<Context>()
11
7
 
12
- const item: SessionItem = {
13
- id: randomUUID(),
14
- sessionId: sid,
15
- text: payload.text,
16
- createdAt: new Date().toISOString(),
17
- }
18
-
19
- return await resource.create(item)
20
- })
8
+ export const add = handle.body(session.add, async (payload, context, request) =>
9
+ await makeSessionModel(context, request.params.sid).add(payload.text))
@@ -1,15 +1,9 @@
1
- import { handleParams } from '@owlmeans/server-app'
2
- import type { SessionItem, SessionParams } from '__APP_SLUG__-common'
3
- import { SESSION_ITEMS } from '../../consts.js'
1
+ import { handlers } from '@owlmeans/server-app'
2
+ import { session } from '__APP_SLUG__-common'
3
+ import { makeSessionModel } from '../../models/session.js'
4
4
  import type { Context } from '../../types.js'
5
5
 
6
- export const list = handleParams<SessionParams>(async (params, context) => {
7
- const ctx = context as Context
8
- const resource = ctx.getStaticResource<SessionItem>(SESSION_ITEMS)
6
+ const handle = handlers<Context>()
9
7
 
10
- // The static resource lists every record; filter to this session and sort newest first.
11
- const { items } = await resource.list<SessionItem>()
12
- return items
13
- .filter(item => item.sessionId === params.sid)
14
- .sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1))
15
- })
8
+ export const list = handle.params(session.list, async (params, context) =>
9
+ await makeSessionModel(context, params.sid).list())
@@ -1,18 +1,9 @@
1
- import { handleParams } from '@owlmeans/server-app'
2
- import type { ItemParams, SessionItem } from '__APP_SLUG__-common'
3
- import { SESSION_ITEMS } from '../../consts.js'
1
+ import { handlers } from '@owlmeans/server-app'
2
+ import { session } from '__APP_SLUG__-common'
3
+ import { makeSessionModel } from '../../models/session.js'
4
4
  import type { Context } from '../../types.js'
5
5
 
6
- export const remove = handleParams<ItemParams>(async (params, context) => {
7
- const ctx = context as Context
8
- const resource = ctx.getStaticResource<SessionItem>(SESSION_ITEMS)
6
+ const handle = handlers<Context>()
9
7
 
10
- const existing = await resource.load<SessionItem>(params.id)
11
- // Only remove the item if it belongs to the requesting session.
12
- if (existing == null || existing.sessionId !== params.sid) {
13
- return { removed: false }
14
- }
15
-
16
- await resource.delete(params.id)
17
- return { removed: true }
18
- })
8
+ export const remove = handle.params(session.remove, async (params, context) =>
9
+ await makeSessionModel(context, params.sid).remove(params.id))
@@ -1,8 +1,15 @@
1
1
  import { config } from '@owlmeans/server-app'
2
2
  import { APP_API, commonConfig } from '__APP_SLUG__-common'
3
3
  import type { Config } from './types.js'
4
+ // The module augmentation that gives the config its `log` field — a side-effect import only.
5
+ import type {} from '@owlmeans/log'
4
6
 
5
7
  // The server listens on the APP_API service route's port (3000), declared in common/config.ts.
6
8
  const cfg = config<Config>(APP_API, commonConfig as Config)
7
9
 
10
+ // The log level comes from the runtime environment, never from code: `info` unless LOG_LEVEL
11
+ // says otherwise; LOG_DEBUG lists scopes forced to debug (`*` for all). Bun reads
12
+ // `sources/api/.env` on its own.
13
+ cfg.log = { level: process.env.LOG_LEVEL || 'info', debug: process.env.LOG_DEBUG ?? '' }
14
+
8
15
  export default cfg
@@ -0,0 +1,11 @@
1
+ import { makeContext as makeBasicContext } from '@owlmeans/server-app'
2
+ import type { Config, Context } from './types.js'
3
+
4
+ /**
5
+ * Where the app's resources are registered. `@owlmeans/static-resource` is already a dependency,
6
+ * so `appendStaticResource<C, T>(context, ALIAS)` gives you an in-memory store with no database
7
+ * behind it; a mongo/postgres resource takes its place once the data has to outlive the process.
8
+ * Whatever you append here must also widen `Context` in `types.ts`, or the getter will not exist.
9
+ */
10
+ export const makeContext = <C extends Config, T extends Context<C>>(cfg: C): T =>
11
+ makeBasicContext<C, T>(cfg, true)
@@ -0,0 +1,4 @@
1
+ import { entrypoints } from '@owlmeans/server-app'
2
+
3
+ // The bare shell has no API declarations yet. Bind new protocols here as they are added.
4
+ export const appBindings = [...entrypoints]
@@ -0,0 +1,13 @@
1
+ import { entrypoints } from '@owlmeans/server-app'
2
+ import { bind } from '@owlmeans/server-entrypoint'
3
+ import { appProtocols } from '__APP_SLUG__-common'
4
+ import * as handlers from './app/session/index.js'
5
+
6
+ /** Local server bindings for the shared session protocol tree. */
7
+ export const appBindings = [
8
+ ...entrypoints,
9
+ bind(appProtocols.api.session.base),
10
+ bind(appProtocols.api.session.list, handlers.list),
11
+ bind(appProtocols.api.session.add, handlers.add),
12
+ bind(appProtocols.api.session.remove, handlers.remove),
13
+ ]
@@ -1,9 +1,15 @@
1
+ import { logger } from '@owlmeans/log'
1
2
  import { main } from '@owlmeans/server-app'
2
3
  import config from './config.js'
3
4
  import { makeContext } from './context.js'
4
- import { appModules } from './modules.js'
5
+ import { appBindings } from './entrypoints.js'
5
6
  import type { Config, Context } from './types.js'
6
7
 
8
+ const log = logger('api')
9
+
7
10
  const context = makeContext<Config, Context>(config)
8
11
 
9
- main<{}, Config, Context>(context, appModules)
12
+ main<{}, Config, Context>(context, appBindings).catch(error => {
13
+ log.error('Start failed', error)
14
+ process.exit(1)
15
+ })
@@ -0,0 +1,14 @@
1
+ import type { SessionItem } from '__APP_SLUG__-common'
2
+
3
+ /**
4
+ * The items of ONE browser session. The session id is bound when the model is built, so no
5
+ * member can reach another session's items; the member names are the session endpoints' keys.
6
+ */
7
+ export interface SessionModel {
8
+ /** This session's items, newest first. */
9
+ list: () => Promise<SessionItem[]>
10
+ /** Store a new item under this session. */
11
+ add: (text: string) => Promise<SessionItem>
12
+ /** Remove an item — only when it belongs to this session. */
13
+ remove: (id: string) => Promise<{ removed: boolean }>
14
+ }
@@ -0,0 +1,43 @@
1
+ import { randomUUID } from 'node:crypto'
2
+ import type { SessionItem } from '__APP_SLUG__-common'
3
+ import { SESSION_ITEMS } from '../consts.js'
4
+ import type { Context } from '../types.js'
5
+ import type { SessionModel } from './session/types.js'
6
+
7
+ /**
8
+ * The session domain, bound to the context that holds its resource and to the session it serves.
9
+ * Built where it is used — `makeSessionModel(context, sid).list()` — never stored.
10
+ */
11
+ export const makeSessionModel = (context: Context, sid: string): SessionModel => {
12
+ const resource = context.getStaticResource<SessionItem>(SESSION_ITEMS)
13
+
14
+ const list: SessionModel['list'] = async () => {
15
+ // The resource answers the whole question — this session's items, newest first.
16
+ const { items } = await resource.list(
17
+ { sessionId: sid },
18
+ { sort: [{ field: 'createdAt', order: 'desc' }] }
19
+ )
20
+
21
+ return items
22
+ }
23
+
24
+ const add: SessionModel['add'] = async text => await resource.create({
25
+ id: randomUUID(),
26
+ sessionId: sid,
27
+ text,
28
+ createdAt: new Date().toISOString(),
29
+ })
30
+
31
+ const remove: SessionModel['remove'] = async id => {
32
+ const existing = await resource.load(id)
33
+ // Only remove the item if it belongs to this session.
34
+ if (existing == null || existing.sessionId !== sid) {
35
+ return { removed: false }
36
+ }
37
+
38
+ await resource.delete(id)
39
+ return { removed: true }
40
+ }
41
+
42
+ return { list, add, remove }
43
+ }
@@ -0,0 +1,5 @@
1
+ import type { AppConfig, AppContext } from '@owlmeans/server-app'
2
+
3
+ export interface Config extends AppConfig {}
4
+
5
+ export interface Context<C extends Config = Config> extends AppContext<C> {}
@@ -19,16 +19,16 @@
19
19
  "typecheck": "tsc -b"
20
20
  },
21
21
  "dependencies": {
22
- "@owlmeans/config": "^0.1.16",
23
- "@owlmeans/entrypoint": "^0.1.16",
24
- "@owlmeans/error": "^0.1.16",
25
- "@owlmeans/resource": "^0.1.16",
26
- "@owlmeans/route": "^0.1.16",
27
- "ajv": "^8.17.1"
22
+ "@owlmeans/config": "^0.1.18-rc.44",
23
+ "@owlmeans/entrypoint": "^0.1.18-rc.41",
24
+ "@owlmeans/error": "^0.1.18-rc.38",
25
+ "@owlmeans/resource": "^0.1.18-rc.40",
26
+ "@owlmeans/route": "^0.1.18-rc.35",
27
+ "ajv": "^8.20.0"
28
28
  },
29
29
  "devDependencies": {
30
- "@owlmeans/dep-config": "^0.1.16",
31
- "@types/node": "^24.10.1",
30
+ "@owlmeans/dep-config": "^0.1.18-rc.6",
31
+ "@types/node": "^26.6.4",
32
32
  "typescript": "^7.0.2"
33
33
  }
34
34
  }
@@ -18,7 +18,8 @@ service({
18
18
  base: 'api',
19
19
  }, cfg)
20
20
 
21
- cfg.debug = { all: true }
21
+ // No log level here: this file runs in Bun AND in the browser, so each runtime's own config.ts
22
+ // sets `cfg.log` from its environment (api: LOG_LEVEL / LOG_DEBUG, web: VITE_LOG_LEVEL / VITE_LOG_DEBUG).
22
23
  cfg.alias = APP
23
24
  // Local dev serves the API over plain HTTP. Without this the web client builds https:// URLs
24
25
  // and every call fails. In production put the API behind TLS and remove this line.
@@ -0,0 +1,8 @@
1
+ /** Service aliases shared between web and api. */
2
+ export const APP = '__APP_SLUG__'
3
+ export const APP_WEB = '__APP_SLUG__-web'
4
+ export const APP_API = '__APP_SLUG__-api'
5
+
6
+ /** Local development ports. */
7
+ export const WEB_PORT = 3001
8
+ export const API_PORT = 3000
@@ -6,16 +6,3 @@ export const APP_API = '__APP_SLUG__-api'
6
6
  /** Local development ports. */
7
7
  export const WEB_PORT = 3001
8
8
  export const API_PORT = 3000
9
-
10
- /** Backend (API) entrypoint identifiers. */
11
- export const session = {
12
- base: '__APP_SLUG__:api:session',
13
- list: '__APP_SLUG__:api:session:list',
14
- add: '__APP_SLUG__:api:session:add',
15
- remove: '__APP_SLUG__:api:session:remove',
16
- }
17
-
18
- /** Frontend (web) entrypoint identifiers. */
19
- export const web = {
20
- session: '__APP_SLUG__:web:session',
21
- }
@@ -0,0 +1,14 @@
1
+ import { openProtocol } from '@owlmeans/entrypoint'
2
+ import { BASE, HOME } from '@owlmeans/context'
3
+ import { frontend, route } from '@owlmeans/route'
4
+
5
+ const webBase = openProtocol(route(BASE, '/', frontend()))
6
+
7
+ /** The shared immutable protocol tree. Add API declarations below `api` as the shell grows. */
8
+ export const appProtocols = {
9
+ api: {},
10
+ web: {
11
+ base: webBase,
12
+ home: openProtocol(route(HOME, '/', frontend({ default: true, parent: webBase }))),
13
+ },
14
+ }
@@ -0,0 +1,60 @@
1
+ import { contract, openProtocol, protocol, typed } from '@owlmeans/entrypoint'
2
+ import { route, RouteMethod, frontend } from '@owlmeans/route'
3
+ import { AddItemSchema, ItemParamsSchema, SessionParamsSchema } from './schemas.js'
4
+ import type { SessionItem } from './types.js'
5
+
6
+ const aliases = {
7
+ session: {
8
+ base: '__APP_SLUG__:api:session',
9
+ list: '__APP_SLUG__:api:session:list',
10
+ add: '__APP_SLUG__:api:session:add',
11
+ remove: '__APP_SLUG__:api:session:remove',
12
+ },
13
+ web: {
14
+ base: '__APP_SLUG__:web:base',
15
+ home: '__APP_SLUG__:web:home',
16
+ session: '__APP_SLUG__:web:session',
17
+ about: '__APP_SLUG__:web:about',
18
+ },
19
+ }
20
+
21
+ const sessionBase = protocol(route(aliases.session.base, '/session'), contract())
22
+ const webBase = openProtocol(route(aliases.web.base, '/', frontend()))
23
+
24
+ /**
25
+ * Shared entrypoint declarations. The api materializes these with handlers; the web
26
+ * materializes them with screen components and calls them. Routes resolve under the
27
+ * api service `base` (`/api`), so e.g. `session.list` → `GET /api/session/:sid/items`.
28
+ */
29
+ export const session = {
30
+ base: sessionBase,
31
+ list: protocol(
32
+ route(aliases.session.list, '/:sid/items', { parent: sessionBase, method: RouteMethod.GET }),
33
+ contract.request({ params: SessionParamsSchema }, typed<SessionItem[]>()),
34
+ ),
35
+ add: protocol(
36
+ route(aliases.session.add, '/:sid/items', { parent: sessionBase, method: RouteMethod.POST }),
37
+ contract.request({
38
+ params: SessionParamsSchema,
39
+ body: AddItemSchema,
40
+ }, typed<SessionItem>()),
41
+ ),
42
+ remove: protocol(
43
+ route(aliases.session.remove, '/:sid/items/:id', { parent: sessionBase, method: RouteMethod.DELETE }),
44
+ contract.request({ params: ItemParamsSchema }, typed<{ removed: boolean }>()),
45
+ ),
46
+ }
47
+
48
+ /** Frontend routes are protocol declarations too; their renderer is bound by the web project. */
49
+ export const web = {
50
+ base: webBase,
51
+ home: openProtocol(route(aliases.web.home, '/', frontend({ default: true, parent: webBase }))),
52
+ session: openProtocol(route(aliases.web.session, '/session', frontend({ parent: webBase }))),
53
+ about: openProtocol(route(aliases.web.about, '/about', frontend({ parent: webBase }))),
54
+ }
55
+
56
+ /** The shared immutable protocol tree. Runtime packages bind their own local handlers and screens. */
57
+ export const appProtocols = Object.freeze({
58
+ api: Object.freeze({ session }),
59
+ web: Object.freeze(web),
60
+ })
@@ -0,0 +1,3 @@
1
+ export * from './consts.js'
2
+ export * from './config.js'
3
+ export * from './entrypoints.js'
@@ -2,4 +2,4 @@ export * from './consts.js'
2
2
  export * from './types.js'
3
3
  export * from './schemas.js'
4
4
  export * from './config.js'
5
- export * from './modules.js'
5
+ export * from './entrypoints.js'
@@ -1,25 +1,25 @@
1
- import type { JSONSchemaType } from 'ajv'
1
+ import { schema } from '@owlmeans/entrypoint'
2
2
  import type { AddItemPayload, ItemParams, SessionParams } from './types.js'
3
3
 
4
- export const AddItemSchema: JSONSchemaType<AddItemPayload> = {
4
+ export const AddItemSchema = schema<AddItemPayload>({
5
5
  type: 'object',
6
6
  properties: {
7
7
  text: { type: 'string', minLength: 1, maxLength: 280 },
8
8
  },
9
9
  required: ['text'],
10
10
  additionalProperties: false,
11
- }
11
+ })
12
12
 
13
- export const SessionParamsSchema: JSONSchemaType<SessionParams> = {
13
+ export const SessionParamsSchema = schema<SessionParams>({
14
14
  type: 'object',
15
15
  properties: {
16
16
  sid: { type: 'string', minLength: 1 },
17
17
  },
18
18
  required: ['sid'],
19
19
  additionalProperties: false,
20
- }
20
+ })
21
21
 
22
- export const ItemParamsSchema: JSONSchemaType<ItemParams> = {
22
+ export const ItemParamsSchema = schema<ItemParams>({
23
23
  type: 'object',
24
24
  properties: {
25
25
  sid: { type: 'string', minLength: 1 },
@@ -27,4 +27,4 @@ export const ItemParamsSchema: JSONSchemaType<ItemParams> = {
27
27
  },
28
28
  required: ['sid', 'id'],
29
29
  additionalProperties: false,
30
- }
30
+ })
@@ -1,9 +1,11 @@
1
1
  <!doctype html>
2
- <html lang="en">
2
+ <html lang="__APP_LANG__">
3
3
 
4
4
  <head>
5
5
  <meta charset="UTF-8" />
6
6
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
7
+ <meta name="application-name" content="__APP_NAME__" />
8
+ <meta name="description" content="__APP_DESCRIPTION__" />
7
9
  <title>__APP_NAME__</title>
8
10
  </head>
9
11