@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.
- package/README.md +49 -5
- package/build/args/types.d.ts +9 -0
- package/build/args/types.d.ts.map +1 -0
- package/build/args/types.js +2 -0
- package/build/args/types.js.map +1 -0
- package/build/args.d.ts +3 -20
- package/build/args.d.ts.map +1 -1
- package/build/args.js +121 -88
- package/build/args.js.map +1 -1
- package/build/bin.js +3 -3
- package/build/bin.js.map +1 -1
- package/build/consts.d.ts +6 -0
- package/build/consts.d.ts.map +1 -0
- package/build/consts.js +6 -0
- package/build/consts.js.map +1 -0
- package/build/consts.local.d.ts +12 -0
- package/build/consts.local.d.ts.map +1 -0
- package/build/consts.local.js +49 -0
- package/build/consts.local.js.map +1 -0
- package/build/index.d.ts +11 -4
- package/build/index.d.ts.map +1 -1
- package/build/index.js +5 -2
- package/build/index.js.map +1 -1
- package/build/naming/types.d.ts +14 -0
- package/build/naming/types.d.ts.map +1 -0
- package/build/naming/types.js +2 -0
- package/build/naming/types.js.map +1 -0
- package/build/naming.d.ts +4 -0
- package/build/naming.d.ts.map +1 -0
- package/build/naming.js +18 -0
- package/build/naming.js.map +1 -0
- package/build/run.d.ts +1 -1
- package/build/run.d.ts.map +1 -1
- package/build/run.js +23 -17
- package/build/run.js.map +1 -1
- package/build/scaffold.d.ts +8 -0
- package/build/scaffold.d.ts.map +1 -0
- package/build/scaffold.js +19 -0
- package/build/scaffold.js.map +1 -0
- package/build/template/types.d.ts +16 -0
- package/build/template/types.d.ts.map +1 -0
- package/build/template/types.js +2 -0
- package/build/template/types.js.map +1 -0
- package/build/template.d.ts +3 -16
- package/build/template.d.ts.map +1 -1
- package/build/template.js +69 -52
- package/build/template.js.map +1 -1
- package/build/types.d.ts +61 -0
- package/build/types.d.ts.map +1 -0
- package/build/types.js +2 -0
- package/build/types.js.map +1 -0
- package/package.json +5 -4
- package/template/AGENTS.md +61 -2
- package/template/README.bare.md +70 -0
- package/template/README.md +9 -60
- package/template/_agents/scripts/link-skills.sh +327 -15
- package/template/_agents/skills/agent-memory/SKILL.md +12 -11
- package/template/_agents/skills/getting-started/SKILL.md +38 -79
- package/template/_agents/skills/logging/SKILL.md +41 -0
- package/template/_agents/skills/memory-promotion/SKILL.md +10 -4
- package/template/_agents/skills/memory-recompact/SKILL.md +15 -14
- package/template/_agents/skills/owlmeans-code-structure/SKILL.md +182 -0
- package/template/_agents/skills/reuse-code/SKILL.md +56 -10
- package/template/_agents/skills/self-education/SKILL.md +25 -5
- package/template/_agents/skills/skill-authoring/SKILL.md +78 -12
- package/template/_bare.json +24 -0
- package/template/_gitignore +8 -0
- package/template/bunfig.toml +2 -0
- package/template/package.json +3 -2
- package/template/sources/api/package.json +5 -4
- package/template/sources/api/src/app/session/add.ts +6 -17
- package/template/sources/api/src/app/session/list.ts +6 -12
- package/template/sources/api/src/app/session/remove.ts +6 -15
- package/template/sources/api/src/config.ts +7 -0
- package/template/sources/api/src/context.bare.ts +11 -0
- package/template/sources/api/src/entrypoints.bare.ts +4 -0
- package/template/sources/api/src/entrypoints.ts +13 -0
- package/template/sources/api/src/index.ts +8 -2
- package/template/sources/api/src/models/session/types.ts +14 -0
- package/template/sources/api/src/models/session.ts +43 -0
- package/template/sources/api/src/types.bare.ts +5 -0
- package/template/sources/common/package.json +8 -8
- package/template/sources/common/src/config.ts +2 -1
- package/template/sources/common/src/consts.bare.ts +8 -0
- package/template/sources/common/src/consts.ts +0 -13
- package/template/sources/common/src/entrypoints.bare.ts +14 -0
- package/template/sources/common/src/entrypoints.ts +60 -0
- package/template/sources/common/src/index.bare.ts +3 -0
- package/template/sources/common/src/index.ts +1 -1
- package/template/sources/common/src/schemas.ts +7 -7
- package/template/sources/web/index.html +3 -1
- package/template/sources/web/package.json +33 -30
- package/template/sources/web/src/components/ui/dropdown-menu.tsx +257 -0
- package/template/sources/web/src/components/ui/navigation-menu.tsx +169 -0
- package/template/sources/web/src/config.ts +8 -0
- package/template/sources/web/src/consts.ts +14 -0
- package/template/sources/web/src/context.bare.ts +13 -0
- package/template/sources/web/src/context.ts +12 -2
- package/template/sources/web/src/entrypoints.bare.ts +13 -0
- package/template/sources/web/src/entrypoints.ts +16 -0
- package/template/sources/web/src/index.css +7 -0
- package/template/sources/web/src/index.tsx +2 -2
- package/template/sources/web/src/layout/main.tsx +17 -19
- package/template/sources/web/src/nav.bare.ts +23 -0
- package/template/sources/web/src/nav.ts +23 -0
- package/template/sources/web/src/screens/about.tsx +19 -0
- package/template/sources/web/src/screens/home.bare.tsx +17 -0
- package/template/sources/web/src/screens/session.tsx +30 -17
- package/template/sources/web/src/vite-env.d.ts +8 -0
- package/template/sources/web/vite.config.ts +3 -2
- package/template/CLAUDE.md +0 -13
- package/template/sources/api/src/modules.ts +0 -11
- package/template/sources/common/src/modules.ts +0 -26
- package/template/sources/web/src/components/nav/main.tsx +0 -15
- 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
|
|
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 —
|
|
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
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
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
|
|
65
|
-
whose skill is gone. The links are gitignored and are recreated at session start
|
|
66
|
-
|
|
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.
|
|
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
|
+
}
|
package/template/_gitignore
CHANGED
|
@@ -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/
|
package/template/package.json
CHANGED
|
@@ -3,14 +3,15 @@
|
|
|
3
3
|
"version": "0.1.0",
|
|
4
4
|
"private": true,
|
|
5
5
|
"type": "module",
|
|
6
|
-
"packageManager": "bun@1.
|
|
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/
|
|
15
|
-
"@owlmeans/
|
|
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.
|
|
20
|
-
"@types/node": "^
|
|
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 {
|
|
2
|
-
import {
|
|
3
|
-
import
|
|
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
|
-
|
|
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
|
-
|
|
13
|
-
|
|
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 {
|
|
2
|
-
import
|
|
3
|
-
import {
|
|
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
|
-
|
|
7
|
-
const ctx = context as Context
|
|
8
|
-
const resource = ctx.getStaticResource<SessionItem>(SESSION_ITEMS)
|
|
6
|
+
const handle = handlers<Context>()
|
|
9
7
|
|
|
10
|
-
|
|
11
|
-
|
|
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 {
|
|
2
|
-
import
|
|
3
|
-
import {
|
|
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
|
-
|
|
7
|
-
const ctx = context as Context
|
|
8
|
-
const resource = ctx.getStaticResource<SessionItem>(SESSION_ITEMS)
|
|
6
|
+
const handle = handlers<Context>()
|
|
9
7
|
|
|
10
|
-
|
|
11
|
-
|
|
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,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 {
|
|
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,
|
|
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
|
+
}
|
|
@@ -19,16 +19,16 @@
|
|
|
19
19
|
"typecheck": "tsc -b"
|
|
20
20
|
},
|
|
21
21
|
"dependencies": {
|
|
22
|
-
"@owlmeans/config": "^0.1.
|
|
23
|
-
"@owlmeans/entrypoint": "^0.1.
|
|
24
|
-
"@owlmeans/error": "^0.1.
|
|
25
|
-
"@owlmeans/resource": "^0.1.
|
|
26
|
-
"@owlmeans/route": "^0.1.
|
|
27
|
-
"ajv": "^8.
|
|
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.
|
|
31
|
-
"@types/node": "^
|
|
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
|
-
|
|
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
|
+
})
|
|
@@ -1,25 +1,25 @@
|
|
|
1
|
-
import
|
|
1
|
+
import { schema } from '@owlmeans/entrypoint'
|
|
2
2
|
import type { AddItemPayload, ItemParams, SessionParams } from './types.js'
|
|
3
3
|
|
|
4
|
-
export const AddItemSchema
|
|
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
|
|
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
|
|
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="
|
|
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
|
|