AppView in a box as a Vite plugin thing
hatk.dev
refactor: rename defineLabels to defineLabel for consistency
Every other define* helper is singular (defineFeed, defineQuery,
defineProcedure, defineHook, defineOG). Align labels to match.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+17
-17
+3
-3
docs/site/guides/labels.md
+3
-3
docs/site/guides/labels.md
···
7
7
8
8
## Defining a label
9
9
10
-
Create a file in `server/` that exports `defineLabels()` with a `definition` and an `evaluate` function:
10
+
Create a file in `server/` that exports `defineLabel()` with a `definition` and an `evaluate` function:
11
11
12
12
```typescript
13
13
// server/labels/explicit.ts
14
-
import { defineLabels } from '$hatk'
14
+
import { defineLabel } from '$hatk'
15
15
16
16
const EXPLICIT_PATTERNS = [/\(explicit\)/i, /\[explicit\]/i, /\bexplicit version\b/i]
17
17
18
-
export default defineLabels({
18
+
export default defineLabel({
19
19
definition: {
20
20
identifier: 'explicit',
21
21
severity: 'inform',
+8
-8
docs/superpowers/plans/2026-03-14-server-directory.md
+8
-8
docs/superpowers/plans/2026-03-14-server-directory.md
···
4
4
5
5
**Goal:** Consolidate all server-side code (feeds, xrpc, hooks, labels, og, setup) into a single `server/` directory scanned by export type, with Vite SSR HMR for handler code.
6
6
7
-
**Architecture:** A new `scanner.ts` module recursively walks `server/`, imports each file, inspects default exports for type tags (`__type: 'feed' | 'query' | 'procedure' | ...`), and routes them to existing subsystem registration. The Vite plugin replaces the `tsx watch` child process with `ssrLoadModule()` for true HMR. Define functions that don't exist yet (`defineSetup`, `defineHook`, `defineLabels`, `defineOG`) are added as thin typed wrappers.
7
+
**Architecture:** A new `scanner.ts` module recursively walks `server/`, imports each file, inspects default exports for type tags (`__type: 'feed' | 'query' | 'procedure' | ...`), and routes them to existing subsystem registration. The Vite plugin replaces the `tsx watch` child process with `ssrLoadModule()` for true HMR. Define functions that don't exist yet (`defineSetup`, `defineHook`, `defineLabel`, `defineOG`) are added as thin typed wrappers.
8
8
9
9
**Tech Stack:** TypeScript, Vite SSR API (`ssrLoadModule`), existing hatk subsystems
10
10
···
62
62
63
63
---
64
64
65
-
### Task 2: Create defineSetup, defineHook, defineLabels, defineOG
65
+
### Task 2: Create defineSetup, defineHook, defineLabel, defineOG
66
66
67
67
New thin define functions for handler types that currently use raw exports.
68
68
69
69
**Files:**
70
70
- Modify: `packages/hatk/src/setup.ts` (add `defineSetup`)
71
71
- Modify: `packages/hatk/src/hooks.ts` (add `defineHook`)
72
-
- Modify: `packages/hatk/src/labels.ts` (add `defineLabels`)
72
+
- Modify: `packages/hatk/src/labels.ts` (add `defineLabel`)
73
73
- Modify: `packages/hatk/src/opengraph.ts` (add `defineOG`)
74
74
75
75
**Step 1: Add `defineSetup` to setup.ts**
···
94
94
}
95
95
```
96
96
97
-
**Step 3: Add `defineLabels` to labels.ts**
97
+
**Step 3: Add `defineLabel` to labels.ts**
98
98
99
99
First read the `LabelDefinition` type from `config.ts`. Add after the `LabelRuleContext` interface (after line 48):
100
100
···
104
104
evaluate?: (ctx: LabelRuleContext) => Promise<string[]>
105
105
}
106
106
107
-
export function defineLabels(module: LabelModule) {
107
+
export function defineLabel(module: LabelModule) {
108
108
return { __type: 'labels' as const, ...module }
109
109
}
110
110
```
···
131
131
132
132
```bash
133
133
git add packages/hatk/src/setup.ts packages/hatk/src/hooks.ts packages/hatk/src/labels.ts packages/hatk/src/opengraph.ts
134
-
git commit -m "feat: add defineSetup, defineHook, defineLabels, defineOG"
134
+
git commit -m "feat: add defineSetup, defineHook, defineLabel, defineOG"
135
135
```
136
136
137
137
---
···
541
541
542
542
### Task 7: Export new define functions from package
543
543
544
-
Users need to import `defineSetup`, `defineHook`, `defineLabels`, `defineOG` from the hatk package.
544
+
Users need to import `defineSetup`, `defineHook`, `defineLabel`, `defineOG` from the hatk package.
545
545
546
546
**Files:**
547
547
- Modify: `packages/hatk/package.json` (add exports if needed)
···
554
554
```typescript
555
555
out += `export { defineSetup } from '@hatk/hatk/setup'\n`
556
556
out += `export { defineHook } from '@hatk/hatk/hooks'\n`
557
-
out += `export { defineLabels } from '@hatk/hatk/labels'\n`
557
+
out += `export { defineLabel } from '@hatk/hatk/labels'\n`
558
558
out += `export { defineOG } from '@hatk/hatk/opengraph'\n`
559
559
```
560
560
+1
-1
docs/superpowers/plans/2026-03-18-docs-overhaul.md
+1
-1
docs/superpowers/plans/2026-03-18-docs-overhaul.md
···
334
334
**Files:**
335
335
- Modify: `docs/site/guides/labels.md`
336
336
337
-
Brief. Show `defineLabels()` with `evaluate()`. Source from actual label files if they exist in templates, otherwise from CLI scaffolding output.
337
+
Brief. Show `defineLabel()` with `evaluate()`. Source from actual label files if they exist in templates, otherwise from CLI scaffolding output.
338
338
339
339
**Step 1: Read current page and find examples**
340
340
**Step 2: Rewrite the page**
+2
-2
docs/superpowers/specs/2026-03-14-server-directory-design.md
+2
-2
docs/superpowers/specs/2026-03-14-server-directory-design.md
···
19
19
| `defineFeed(name, opts)` | Feed generator | handler + hydrator |
20
20
| `defineHook(event, opts)` | Lifecycle hook | event name (e.g. `'on-login'`) |
21
21
| `defineSetup(fn)` | Boot-time setup | runs before server starts |
22
-
| `defineLabels(defs)` | Label definitions | array of label configs |
22
+
| `defineLabel(defs)` | Label definitions | array of label configs |
23
23
| `defineOG(path, fn)` | OpenGraph image | route path, returns JSX |
24
24
25
25
**Execution order:** Setup scripts run first (boot), then all other handlers register. During dev, handler files get Vite SSR HMR — edits reload instantly without restarting the database or indexer.
···
113
113
114
114
**2. Vite SSR integration** — Replace the `tsx watch` spawn in the Vite plugin with Vite's `ssrLoadModule()` for handler files. The hatk core runtime (database, indexer, OAuth) boots once and stays alive. Handler modules get loaded/reloaded through Vite's module graph, giving us HMR for free.
115
115
116
-
**3. Define functions** — `defineQuery`, `defineProcedure`, `defineFeed`, `defineHook`, `defineSetup`, `defineLabels`, `defineOG` all export from `@hatk/hatk`. Each returns a typed descriptor object that the scanner knows how to register. The define functions themselves are thin — they just tag the config with a type and return it.
116
+
**3. Define functions** — `defineQuery`, `defineProcedure`, `defineFeed`, `defineHook`, `defineSetup`, `defineLabel`, `defineOG` all export from `@hatk/hatk`. Each returns a typed descriptor object that the scanner knows how to register. The define functions themselves are thin — they just tag the config with a type and return it.
117
117
118
118
**4. Build output** — `vite build` produces a server entry point alongside static assets. The entry point imports the scanned handlers and boots the hatk runtime. Production runs with `node dist/server.js`.
119
119
+1
-1
docs/superpowers/specs/2026-03-18-docs-overhaul-design.md
+1
-1
docs/superpowers/specs/2026-03-18-docs-overhaul-design.md
···
122
122
123
123
**Seeds** — `seed()` helper with `createAccount`, `createRecord`, `uploadBlob`. Complete seed file example. `hatk seed` and `hatk reset` commands.
124
124
125
-
**Labels** — `defineLabels()` with `evaluate()`. Brief.
125
+
**Labels** — `defineLabel()` with `evaluate()`. Brief.
126
126
127
127
**OpenGraph** — `defineOG()` with Satori. Brief.
128
128
+1
-1
packages/hatk/src/cli.ts
+1
-1
packages/hatk/src/cli.ts
···
1696
1696
out += `export { InvalidRequestError, NotFoundError } from '@hatk/hatk/xrpc'\n`
1697
1697
out += `export { defineSetup } from '@hatk/hatk/setup'\n`
1698
1698
out += `export { defineHook } from '@hatk/hatk/hooks'\n`
1699
-
out += `export { defineLabels } from '@hatk/hatk/labels'\n`
1699
+
out += `export { defineLabel } from '@hatk/hatk/labels'\n`
1700
1700
out += `export { defineOG } from '@hatk/hatk/opengraph'\n`
1701
1701
out += `export { defineRenderer } from '@hatk/hatk/renderer'\n`
1702
1702
out += `export type Ctx<K extends keyof XrpcSchema & keyof Registry> = XrpcContext<\n`