@bitakit/cli 0.2.4 → 0.2.6
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/AGENTS.md +32 -0
- package/README.md +10 -2
- package/package.json +4 -3
- package/skills/bitakit-app-development/README.md +14 -9
- package/skills/bitakit-app-development/SKILL.md +53 -10
- package/skills/bitakit-app-development/references/best-practices.md +211 -0
- package/skills/bitakit-app-development/references/data-and-api.md +321 -0
- package/skills/bitakit-app-development/references/layouts-and-screens.md +219 -0
- package/skills/bitakit-app-development/references/plugins-and-pages.md +9 -12
- package/skills/bitakit-app-development/references/slots.md +29 -18
- package/skills/bitakit-app-development/references/worked-example.md +307 -0
- package/src/add.mjs +39 -11
- package/src/agent-rules.mjs +2 -1
- package/src/build.mjs +49 -18
- package/src/cli.mjs +14 -8
- package/src/doctor.mjs +50 -15
- package/src/project.mjs +4 -1
- package/src/slots.mjs +55 -1
- package/src/templates.mjs +9 -6
|
@@ -0,0 +1,307 @@
|
|
|
1
|
+
# Worked example: a Bookmarks feature from scratch
|
|
2
|
+
|
|
3
|
+
Use this as the model for a new feature: plan it, create the files, check it and report. The
|
|
4
|
+
feature lets users save links, open them and remove them. Every file below passes
|
|
5
|
+
`npm run typecheck` and `npx bitakit doctor` in a create-app app with Shell and App Preferences.
|
|
6
|
+
|
|
7
|
+
## 1. Plan before writing code
|
|
8
|
+
|
|
9
|
+
Map what the user asked for to BitaKit mechanisms, then tell the user the plan in one or two
|
|
10
|
+
sentences.
|
|
11
|
+
|
|
12
|
+
| The user wants | Mechanism | File in `src/plugins/bookmarks/` |
|
|
13
|
+
| -------------------------------- | ---------------------------- | -------------------------------- |
|
|
14
|
+
| A page listing saved links | Page | `ui/pages/index.tsx` |
|
|
15
|
+
| The list, shared by page/Actions | Service with a `store()` | `services/list.ts` |
|
|
16
|
+
| Save and Remove buttons | Actions | `actions/add.ts`, `remove.ts` |
|
|
17
|
+
| A link in the navigation | Navigation Action | `actions/open.ts` |
|
|
18
|
+
| "Open links in a new tab" | Setting | `settings.ts` |
|
|
19
|
+
| Other features may react | Events `added` and `removed` | `events.ts` |
|
|
20
|
+
|
|
21
|
+
## 2. Create the files
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
npx bitakit add plugin bookmarks
|
|
25
|
+
npx bitakit add service bookmarks/list
|
|
26
|
+
npx bitakit add events bookmarks
|
|
27
|
+
npx bitakit add action bookmarks/add
|
|
28
|
+
npx bitakit add action bookmarks/remove
|
|
29
|
+
npx bitakit add settings bookmarks
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
The commands write templates; replace each body with the code below and remove the tutorial
|
|
33
|
+
comments.
|
|
34
|
+
|
|
35
|
+
## 3. Events
|
|
36
|
+
|
|
37
|
+
`src/plugins/bookmarks/events.ts`:
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
import { defineEvents, event } from '@bitakit/core';
|
|
41
|
+
|
|
42
|
+
// Other plugins listen with events.on('bookmarks.added', ...); payloads carry what changed.
|
|
43
|
+
export default defineEvents({
|
|
44
|
+
added: event<{ id: string; url: string }>(),
|
|
45
|
+
removed: event<{ id: string }>(),
|
|
46
|
+
});
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## 4. Service
|
|
50
|
+
|
|
51
|
+
`src/plugins/bookmarks/services/list.ts`:
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
import { defineService } from '@bitakit/core';
|
|
55
|
+
|
|
56
|
+
export type Bookmark = { id: string; title: string; url: string };
|
|
57
|
+
|
|
58
|
+
// Saved links. They live in memory until the service loads and saves them through an API.
|
|
59
|
+
export default defineService(({ store, events }) => {
|
|
60
|
+
const state = store<{ bookmarks: Bookmark[] }>({ bookmarks: [] });
|
|
61
|
+
return {
|
|
62
|
+
state,
|
|
63
|
+
add(url: string) {
|
|
64
|
+
const address = new URL(url);
|
|
65
|
+
const bookmark = { id: crypto.randomUUID(), title: address.hostname, url: address.href };
|
|
66
|
+
state.set((current) => ({ bookmarks: [...current.bookmarks, bookmark] }));
|
|
67
|
+
events.emit('bookmarks.added', { id: bookmark.id, url: bookmark.url });
|
|
68
|
+
},
|
|
69
|
+
remove(id: string) {
|
|
70
|
+
state.set((current) => ({
|
|
71
|
+
bookmarks: current.bookmarks.filter((bookmark) => bookmark.id !== id),
|
|
72
|
+
}));
|
|
73
|
+
events.emit('bookmarks.removed', { id });
|
|
74
|
+
},
|
|
75
|
+
};
|
|
76
|
+
});
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
- The service owns the data; pages and Actions only read it and call its methods.
|
|
80
|
+
- `state.set` builds a new array each time; events go out after the change.
|
|
81
|
+
|
|
82
|
+
## 5. Actions
|
|
83
|
+
|
|
84
|
+
`src/plugins/bookmarks/actions/add.ts`:
|
|
85
|
+
|
|
86
|
+
```ts
|
|
87
|
+
import { defineAction } from '@bitakit/core';
|
|
88
|
+
|
|
89
|
+
export default defineAction<string>({
|
|
90
|
+
title: 'Save',
|
|
91
|
+
// The button stays disabled until the field holds a full URL such as https://example.com.
|
|
92
|
+
enabled: ({ input }) => URL.canParse(input?.trim() ?? ''),
|
|
93
|
+
execute: ({ services, input }) => services.bookmarks.list.add(input.trim()),
|
|
94
|
+
success: 'Bookmark saved',
|
|
95
|
+
});
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
`src/plugins/bookmarks/actions/remove.ts`:
|
|
99
|
+
|
|
100
|
+
```ts
|
|
101
|
+
import { defineAction } from '@bitakit/core';
|
|
102
|
+
|
|
103
|
+
export default defineAction<string>({
|
|
104
|
+
title: 'Remove',
|
|
105
|
+
// Each row has its own pending state.
|
|
106
|
+
concurrency: 'per-input',
|
|
107
|
+
confirm: ({ input, services }) => ({
|
|
108
|
+
title: `Remove ${
|
|
109
|
+
services.bookmarks.list.state.get().bookmarks.find((bookmark) => bookmark.id === input)
|
|
110
|
+
?.title ?? 'this bookmark'
|
|
111
|
+
}?`,
|
|
112
|
+
description: 'The link is deleted from your bookmarks.',
|
|
113
|
+
destructive: true,
|
|
114
|
+
}),
|
|
115
|
+
execute: ({ services, input }) => services.bookmarks.list.remove(input),
|
|
116
|
+
});
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
`src/plugins/bookmarks/actions/open.ts` (written by `add plugin`; shown tidied):
|
|
120
|
+
|
|
121
|
+
```ts
|
|
122
|
+
import { defineAction } from '@bitakit/core';
|
|
123
|
+
|
|
124
|
+
// The navigation entry; the page is ui/pages/index.tsx.
|
|
125
|
+
export default defineAction({
|
|
126
|
+
title: 'Bookmarks',
|
|
127
|
+
href: '/bookmarks',
|
|
128
|
+
slots: ['shell.navigation'],
|
|
129
|
+
});
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
- A confirmation object needs both `title` and `description`.
|
|
133
|
+
- `per-input` lets two rows be removed at once; the default `exclusive` would block the second.
|
|
134
|
+
|
|
135
|
+
## 6. Setting
|
|
136
|
+
|
|
137
|
+
`src/plugins/bookmarks/settings.ts`:
|
|
138
|
+
|
|
139
|
+
```ts
|
|
140
|
+
import { defineSettings, setting } from '@bitakit/core';
|
|
141
|
+
|
|
142
|
+
export default defineSettings(
|
|
143
|
+
{ openInNewTab: setting({ default: true, label: 'Open bookmarks in a new tab' }) },
|
|
144
|
+
{ title: 'Bookmarks' },
|
|
145
|
+
);
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
This adds the page `/settings/bookmarks` with a switch; no UI code is needed.
|
|
149
|
+
|
|
150
|
+
## 7. Page
|
|
151
|
+
|
|
152
|
+
`src/plugins/bookmarks/ui/pages/index.tsx`:
|
|
153
|
+
|
|
154
|
+
```tsx
|
|
155
|
+
'use client';
|
|
156
|
+
import { useState } from 'react';
|
|
157
|
+
import { Action, useServiceState, useSetting } from '@bitakit/ui';
|
|
158
|
+
import {
|
|
159
|
+
Button,
|
|
160
|
+
Input,
|
|
161
|
+
Item,
|
|
162
|
+
ItemActions,
|
|
163
|
+
ItemContent,
|
|
164
|
+
ItemDescription,
|
|
165
|
+
ItemGroup,
|
|
166
|
+
ItemTitle,
|
|
167
|
+
PageHeader,
|
|
168
|
+
} from '@bitakit/ui/components';
|
|
169
|
+
|
|
170
|
+
// Served at /bookmarks. State comes from the bookmarks.list service; buttons run Actions.
|
|
171
|
+
export default function BookmarksPage() {
|
|
172
|
+
const [url, setUrl] = useState('');
|
|
173
|
+
const bookmarks = useServiceState('bookmarks.list', (state) => state.bookmarks, []);
|
|
174
|
+
const openInNewTab = useSetting('bookmarks.openInNewTab').value;
|
|
175
|
+
return (
|
|
176
|
+
<div className="flex flex-col gap-6">
|
|
177
|
+
<PageHeader title="Bookmarks" subtitle="Links you want to come back to." />
|
|
178
|
+
<form className="flex gap-2" onSubmit={(event) => event.preventDefault()}>
|
|
179
|
+
<Input
|
|
180
|
+
value={url}
|
|
181
|
+
type="url"
|
|
182
|
+
placeholder="https://example.com"
|
|
183
|
+
aria-label="Link to save"
|
|
184
|
+
onChange={(event) => setUrl(event.target.value)}
|
|
185
|
+
/>
|
|
186
|
+
{/* Clear the field only when the bookmark was saved. */}
|
|
187
|
+
<Action
|
|
188
|
+
id="bookmarks.add"
|
|
189
|
+
input={url}
|
|
190
|
+
onExecuted={(result) => result.status === 'completed' && setUrl('')}
|
|
191
|
+
>
|
|
192
|
+
<Button type="submit" />
|
|
193
|
+
</Action>
|
|
194
|
+
</form>
|
|
195
|
+
{bookmarks.length ? (
|
|
196
|
+
<ItemGroup>
|
|
197
|
+
{bookmarks.map((bookmark) => (
|
|
198
|
+
<Item key={bookmark.id} variant="outline">
|
|
199
|
+
<ItemContent>
|
|
200
|
+
<ItemTitle>
|
|
201
|
+
<a
|
|
202
|
+
href={bookmark.url}
|
|
203
|
+
{...(openInNewTab ? { target: '_blank', rel: 'noreferrer' } : {})}
|
|
204
|
+
>
|
|
205
|
+
{bookmark.title}
|
|
206
|
+
</a>
|
|
207
|
+
</ItemTitle>
|
|
208
|
+
<ItemDescription>{bookmark.url}</ItemDescription>
|
|
209
|
+
</ItemContent>
|
|
210
|
+
<ItemActions>
|
|
211
|
+
<Action id="bookmarks.remove" input={bookmark.id}>
|
|
212
|
+
<Button variant="outline" size="sm" />
|
|
213
|
+
</Action>
|
|
214
|
+
</ItemActions>
|
|
215
|
+
</Item>
|
|
216
|
+
))}
|
|
217
|
+
</ItemGroup>
|
|
218
|
+
) : (
|
|
219
|
+
<p className="text-sm text-muted-foreground">No bookmarks yet. Paste a link above.</p>
|
|
220
|
+
)}
|
|
221
|
+
</div>
|
|
222
|
+
);
|
|
223
|
+
}
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
- A submit button inside a `<form>` lets Enter save; the Action supplies the label, the disabled
|
|
227
|
+
state and the pending state, so the page sets none of them.
|
|
228
|
+
- The empty `<Button />` children get the Action titles ("Save", "Remove").
|
|
229
|
+
- The page has an empty state; with an API it also needs loading and error states
|
|
230
|
+
([data-and-api.md](data-and-api.md)).
|
|
231
|
+
|
|
232
|
+
## 8. Check it
|
|
233
|
+
|
|
234
|
+
1. `npm run typecheck`, then `npx bitakit doctor`.
|
|
235
|
+
2. Open `/bookmarks` in the running app. Type `https://nextjs.org/docs` and press Enter: the row
|
|
236
|
+
appears and the field clears. With an empty field, Save is disabled.
|
|
237
|
+
3. Click Remove: a dialog asks "Remove nextjs.org?"; Confirm empties the list.
|
|
238
|
+
4. Open `/settings/bookmarks` and switch off "Open bookmarks in a new tab"; links now open in the
|
|
239
|
+
same tab.
|
|
240
|
+
|
|
241
|
+
## 9. Test it (when the app has a test runner)
|
|
242
|
+
|
|
243
|
+
Ask before adding the runner ([testing-and-preview.md](testing-and-preview.md)), then run
|
|
244
|
+
`npx bitakit add test bookmarks` and replace the body. `tests/bookmarks.test.ts`:
|
|
245
|
+
|
|
246
|
+
```ts
|
|
247
|
+
import assert from 'node:assert/strict';
|
|
248
|
+
import test from 'node:test';
|
|
249
|
+
import { defineContract, definePlugin, defineSlot, getService } from '@bitakit/core';
|
|
250
|
+
import { mountPlugin } from '@bitakit/core/testing';
|
|
251
|
+
import type list from '../src/plugins/bookmarks/services/list';
|
|
252
|
+
|
|
253
|
+
const bookmarks = defineContract('bookmarks.list').of<ReturnType<typeof list.create>>();
|
|
254
|
+
// bookmarks.open targets shell.navigation; this stand-in owns that slot so the plugin starts without Shell.
|
|
255
|
+
const shell = definePlugin({
|
|
256
|
+
id: 'shell',
|
|
257
|
+
slots: { navigation: defineSlot({ accepts: 'actions' }) },
|
|
258
|
+
});
|
|
259
|
+
|
|
260
|
+
test('saving and removing a bookmark updates the list and emits events', async () => {
|
|
261
|
+
const plugin = await mountPlugin('src/plugins/bookmarks', { plugins: [shell] });
|
|
262
|
+
try {
|
|
263
|
+
const list = getService(plugin.services, bookmarks);
|
|
264
|
+
|
|
265
|
+
assert.equal((await plugin.execute('add', 'https://example.com/docs')).status, 'completed');
|
|
266
|
+
const [saved] = list.state.get().bookmarks;
|
|
267
|
+
assert.equal(saved?.title, 'example.com');
|
|
268
|
+
assert.deepEqual(plugin.events.recorded.at(-1), {
|
|
269
|
+
type: 'bookmarks.added',
|
|
270
|
+
data: { id: saved?.id, url: 'https://example.com/docs' },
|
|
271
|
+
});
|
|
272
|
+
|
|
273
|
+
// The enabled rule blocks text that is not a URL, so nothing is saved.
|
|
274
|
+
assert.equal((await plugin.execute('add', 'not a link')).status, 'skipped');
|
|
275
|
+
assert.equal(list.state.get().bookmarks.length, 1);
|
|
276
|
+
|
|
277
|
+
list.remove(saved!.id);
|
|
278
|
+
assert.deepEqual(list.state.get().bookmarks, []);
|
|
279
|
+
assert.equal(plugin.events.recorded.at(-1)?.type, 'bookmarks.removed');
|
|
280
|
+
} finally {
|
|
281
|
+
await plugin.stop();
|
|
282
|
+
}
|
|
283
|
+
});
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
- A disabled Action resolves to `{ status: 'skipped' }`; a failing one rejects.
|
|
287
|
+
- `remove` has a confirmation, so the test calls the service method directly.
|
|
288
|
+
|
|
289
|
+
## 10. Report it
|
|
290
|
+
|
|
291
|
+
A good report names what changed, where it appears, how it connects and what was checked:
|
|
292
|
+
|
|
293
|
+
> I added a **Bookmarks** feature in `src/plugins/bookmarks`. It appears as "Bookmarks" in the
|
|
294
|
+
> navigation and at `/bookmarks`: paste a link and press Enter to save it, and use Remove to
|
|
295
|
+
> delete it after a confirmation. The `bookmarks.list` service holds the links, the Save and
|
|
296
|
+
> Remove buttons are the Actions `bookmarks.add` and `bookmarks.remove`, and other features can
|
|
297
|
+
> react to `bookmarks.added` and `bookmarks.removed`. "Open bookmarks in a new tab" is under
|
|
298
|
+
> Settings → Bookmarks. Typecheck and doctor pass, and I tried save, remove and the setting in the
|
|
299
|
+
> browser. The links live in memory, so a reload clears them until we save them through an API.
|
|
300
|
+
|
|
301
|
+
## Extend it
|
|
302
|
+
|
|
303
|
+
- Save the links on a server: [data-and-api.md](data-and-api.md) continues this example.
|
|
304
|
+
- Show the count in the Shell header: contribute `ui/slots/shell.header.end.tsx`
|
|
305
|
+
([slots.md](slots.md)).
|
|
306
|
+
- React in another feature: listen to `bookmarks.added` in that feature's service
|
|
307
|
+
([services-and-events.md](services-and-events.md)).
|
package/src/add.mjs
CHANGED
|
@@ -108,21 +108,12 @@ const singleFile = {
|
|
|
108
108
|
* `events` takes only the plugin: a plugin declares its events once in `events.ts`. `test` also
|
|
109
109
|
* takes only an existing plugin of an app and writes `tests/<plugin>.test.ts` at the app root.
|
|
110
110
|
*/
|
|
111
|
-
export async function addContribution(kind, target, { cwd } = {}) {
|
|
111
|
+
export async function addContribution(kind, target, { cwd, plugin: layoutPlugin } = {}) {
|
|
112
112
|
if (!contributionKinds.includes(kind))
|
|
113
113
|
throw new Error(`Unknown kind "${kind}". Use ${contributionKinds.join(', ')}.`);
|
|
114
114
|
const project = await configuredProject(cwd);
|
|
115
115
|
if (kind === 'test') return addTest(project, target);
|
|
116
|
-
if (kind === 'layout')
|
|
117
|
-
if (project.kind !== 'app')
|
|
118
|
-
throw new Error('Layouts belong to the app: run "bitakit add layout <name>" inside an app.');
|
|
119
|
-
if (!target) throw new Error('Name the layout, for example "bitakit add layout admin".');
|
|
120
|
-
validateName(target, 'layout name');
|
|
121
|
-
const created = await writeNewFiles(project.appDirectory, {
|
|
122
|
-
[`layouts/${target}.tsx`]: layoutFile(target),
|
|
123
|
-
});
|
|
124
|
-
return { project, created, id: target, path: undefined };
|
|
125
|
-
}
|
|
116
|
+
if (kind === 'layout') return addLayout(project, target, layoutPlugin);
|
|
126
117
|
const single = Object.hasOwn(singleFile, kind);
|
|
127
118
|
const example = single
|
|
128
119
|
? `bitakit add ${kind} notes`
|
|
@@ -194,6 +185,43 @@ export async function addContribution(kind, target, { cwd } = {}) {
|
|
|
194
185
|
};
|
|
195
186
|
}
|
|
196
187
|
|
|
188
|
+
/**
|
|
189
|
+
* `bitakit add layout <family>[/<variant>]`: a candidate for the `layout.<family>` slot, in the
|
|
190
|
+
* app's `src/layouts`, an app plugin's `ui/layouts` (`--plugin`) or a plugin package's `ui/layouts`.
|
|
191
|
+
*/
|
|
192
|
+
async function addLayout(project, target, plugin) {
|
|
193
|
+
if (!target)
|
|
194
|
+
throw new Error(
|
|
195
|
+
'Name the layout family, for example "bitakit add layout auth" or "bitakit add layout auth/split".',
|
|
196
|
+
);
|
|
197
|
+
const [family, variant, ...rest] = target.split('/');
|
|
198
|
+
if (rest.length) throw new Error(`Use "<family>" or "<family>/<variant>", not "${target}".`);
|
|
199
|
+
validateName(family, 'layout family');
|
|
200
|
+
if (variant !== undefined) validateName(variant, 'layout variant');
|
|
201
|
+
const file = `${variant === undefined ? family : `${family}/${variant}`}.tsx`;
|
|
202
|
+
let root;
|
|
203
|
+
let folder = 'ui/layouts';
|
|
204
|
+
if (project.kind === 'plugin') {
|
|
205
|
+
if (plugin)
|
|
206
|
+
throw new Error('Inside a plugin package, run "bitakit add layout" without --plugin.');
|
|
207
|
+
root = project.moduleRoot;
|
|
208
|
+
} else if (plugin) {
|
|
209
|
+
validateName(plugin, 'plugin name');
|
|
210
|
+
root = path.join(project.pluginsDirectory, plugin);
|
|
211
|
+
if (!(await exists(root)))
|
|
212
|
+
throw new Error(
|
|
213
|
+
`There is no plugin "${plugin}". Create it first: bitakit add plugin ${plugin}.`,
|
|
214
|
+
);
|
|
215
|
+
} else {
|
|
216
|
+
root = project.appDirectory;
|
|
217
|
+
folder = 'layouts';
|
|
218
|
+
}
|
|
219
|
+
const created = await writeNewFiles(root, {
|
|
220
|
+
[`${folder}/${file}`]: layoutFile(family, variant),
|
|
221
|
+
});
|
|
222
|
+
return { project, created, id: `layout.${family}`, plugin, path: undefined };
|
|
223
|
+
}
|
|
224
|
+
|
|
197
225
|
/** What `mountPlugin` needs under Node besides `@bitakit/core`, as the testing guide lists it. */
|
|
198
226
|
const testDependencies = ['@bitakit/discovery', 'jiti', 'typescript', '@types/node'];
|
|
199
227
|
|
package/src/agent-rules.mjs
CHANGED
|
@@ -88,7 +88,8 @@ the file path is the ID. Discovery generates \`src/bitakit.gen.*\`; there is no
|
|
|
88
88
|
React only under \`ui/\`. Use \`@bitakit/ui/components\` and the app theme; do not restyle locally or
|
|
89
89
|
import package CSS from JavaScript (discovery writes \`src/bitakit.gen.css\`).
|
|
90
90
|
- Do not rebuild what BitaKit provides: no own registries, event buses, settings stores or button state.
|
|
91
|
-
${shell ? "- Shell: place an Action with `slots: ['shell.navigation']` or `['shell.toolbar']`; header content goes in `ui/slots/shell.header.end.tsx`.\n" : ''}- App-owned routes stay native framework routes in \`${routes}\`; layouts live in \`src/layouts/<
|
|
91
|
+
${shell ? "- Shell: place an Action with `slots: ['shell.navigation']` or `['shell.toolbar']`; header content goes in `ui/slots/shell.header.end.tsx`.\n" : ''}- App-owned routes stay native framework routes in \`${routes}\`; layouts live in \`src/layouts/<family>.tsx\` (pages pick one with \`export const layout\`).
|
|
92
|
+
- Each installed \`@bitakit/*\` package explains itself in \`node_modules/@bitakit/<name>/AGENTS.md\`; read it before using the package.
|
|
92
93
|
- Create files with \`npx bitakit add plugin <name>\` and \`npx bitakit add <kind> <name>/<file>\` (\`events\` and
|
|
93
94
|
\`settings\` take only \`<name>\`); list IDs with \`npx bitakit info --json\` and slots with \`npx bitakit slots\`; check with \`npx bitakit doctor\` and \`npm run typecheck\`.
|
|
94
95
|
- For feature work, use the project-local \`bitakit-app-development\` skill (\`$bitakit-app-development\` in Codex,
|
package/src/build.mjs
CHANGED
|
@@ -68,14 +68,28 @@ export async function buildPlugin({ cwd, check = false } = {}) {
|
|
|
68
68
|
await writeFile(path.join(dist, 'plugin.js'), entry(id, module, manifest, metadata, local));
|
|
69
69
|
// Derived tooling hints travel with the entry; the source declarations remain the authority.
|
|
70
70
|
const slotInfo = await describeDefinitions(module.slotDefinitions, {
|
|
71
|
-
helper: 'defineSlot',
|
|
71
|
+
helper: 'defineSlot',
|
|
72
|
+
moduleId: id,
|
|
73
|
+
properties: ['accepts', 'policy'],
|
|
72
74
|
});
|
|
73
75
|
const source = (file) => path.relative(module.directory, file).split(path.sep).join('/');
|
|
74
|
-
await writeFile(
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
76
|
+
await writeFile(
|
|
77
|
+
path.join(dist, 'plugin.slots.json'),
|
|
78
|
+
JSON.stringify(
|
|
79
|
+
{
|
|
80
|
+
version: 1,
|
|
81
|
+
definitions: slotInfo.definitions.map((item) => ({
|
|
82
|
+
...item,
|
|
83
|
+
file: source(item.file),
|
|
84
|
+
plugin: id,
|
|
85
|
+
policy: item.policy ?? 'list',
|
|
86
|
+
})),
|
|
87
|
+
unresolved: slotInfo.unresolved.map(source),
|
|
88
|
+
},
|
|
89
|
+
null,
|
|
90
|
+
2,
|
|
91
|
+
) + '\n',
|
|
92
|
+
);
|
|
79
93
|
await writeFile(
|
|
80
94
|
path.join(dist, 'plugin.d.ts'),
|
|
81
95
|
`${declarations(id, module, (file) => local(file))}import type { Plugin } from '@bitakit/core';
|
|
@@ -89,15 +103,19 @@ export default plugin;
|
|
|
89
103
|
for (const file of module.locales)
|
|
90
104
|
await cp(file, path.join(dist, 'locales', path.basename(file)));
|
|
91
105
|
}
|
|
92
|
-
const styles = (value) =>
|
|
93
|
-
.
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
106
|
+
const styles = (value) =>
|
|
107
|
+
(value === undefined ? [] : Array.isArray(value) ? value : [value]).map(
|
|
108
|
+
(entry) => `${manifest.name}/${entry.replace(/^\.\//, '')}`,
|
|
109
|
+
);
|
|
110
|
+
await validatePackageStyles([
|
|
111
|
+
{
|
|
112
|
+
name: manifest.name,
|
|
113
|
+
manifestFile: path.join(root, 'package.json'),
|
|
114
|
+
manifest,
|
|
115
|
+
styles: styles(metadata.styles),
|
|
116
|
+
theme: styles(metadata.theme),
|
|
117
|
+
},
|
|
118
|
+
]);
|
|
101
119
|
return { id, module, dist };
|
|
102
120
|
}
|
|
103
121
|
|
|
@@ -157,11 +175,23 @@ function entry(id, module, manifest, metadata, local) {
|
|
|
157
175
|
return `discoveredFile(${name}, ${quote(item.path)}, ${quote(path.relative(module.directory, item.file).split(path.sep).join('/'))})`;
|
|
158
176
|
});
|
|
159
177
|
const info = {};
|
|
160
|
-
for (const key of [
|
|
178
|
+
for (const key of [
|
|
179
|
+
'name',
|
|
180
|
+
'version',
|
|
181
|
+
'description',
|
|
182
|
+
'author',
|
|
183
|
+
'homepage',
|
|
184
|
+
'bugs',
|
|
185
|
+
'license',
|
|
186
|
+
'coverImage',
|
|
187
|
+
'tags',
|
|
188
|
+
])
|
|
161
189
|
if (manifest[key] !== undefined) info[key] = manifest[key];
|
|
162
190
|
const services = discovered(module.services);
|
|
163
191
|
const settings = discovered(module.settings);
|
|
164
|
-
const settingsPage = module.settingsPage
|
|
192
|
+
const settingsPage = module.settingsPage
|
|
193
|
+
? `pluginSettingsPage(${load(module.settingsPage, true)})`
|
|
194
|
+
: undefined;
|
|
165
195
|
const slotDefinitions = discovered(module.slotDefinitions);
|
|
166
196
|
const actions = discovered(module.actions);
|
|
167
197
|
const configs = discovered(module.configs);
|
|
@@ -172,7 +202,8 @@ function entry(id, module, manifest, metadata, local) {
|
|
|
172
202
|
`pluginPage(${load(item.file, true)}, ${quote(`/${id}${item.path ? `/${item.path.split('.').join('/')}` : ''}`)})`,
|
|
173
203
|
);
|
|
174
204
|
const slots = module.slots.map(
|
|
175
|
-
(item) =>
|
|
205
|
+
(item) =>
|
|
206
|
+
`pluginSlot(${load(item.file, true)}, ${quote(item.path)}, ${quote(path.relative(module.directory, item.file).split(path.sep).join('/'))})`,
|
|
176
207
|
);
|
|
177
208
|
const providers = module.providers.map(
|
|
178
209
|
(item) => `pluginProvider(${load(item.file, true)}, ${quote(`${id}.${item.path}`)})`,
|
package/src/cli.mjs
CHANGED
|
@@ -51,21 +51,26 @@ add
|
|
|
51
51
|
: `\nThe dev server picks it up automatically; no registration needed.\n`,
|
|
52
52
|
);
|
|
53
53
|
});
|
|
54
|
-
for (const kind of contributionKinds)
|
|
55
|
-
add
|
|
56
|
-
|
|
54
|
+
for (const kind of contributionKinds) {
|
|
55
|
+
const command = add.command(kind);
|
|
56
|
+
if (kind === 'layout')
|
|
57
|
+
command.option(
|
|
58
|
+
'--plugin <id>',
|
|
59
|
+
"write the layout into an app plugin's ui/layouts instead of src/layouts",
|
|
60
|
+
);
|
|
61
|
+
command
|
|
57
62
|
.argument(
|
|
58
63
|
kind === 'events' || kind === 'settings' || kind === 'settings-page'
|
|
59
64
|
? '[plugin]'
|
|
60
65
|
: kind === 'layout'
|
|
61
|
-
? '<
|
|
66
|
+
? '<family>'
|
|
62
67
|
: kind === 'test'
|
|
63
68
|
? '<plugin>'
|
|
64
69
|
: '<target>',
|
|
65
70
|
kind === 'events' || kind === 'settings' || kind === 'settings-page'
|
|
66
71
|
? `the plugin that owns the ${kind}; omit it inside a plugin package`
|
|
67
72
|
: kind === 'layout'
|
|
68
|
-
? 'the layout
|
|
73
|
+
? '"<family>" or "<family>/<variant>": a candidate for the layout.<family> slot; pages choose the family with export const layout'
|
|
69
74
|
: kind === 'test'
|
|
70
75
|
? 'an existing plugin of the app, for example "notes"'
|
|
71
76
|
: kind === 'slot'
|
|
@@ -78,13 +83,13 @@ for (const kind of contributionKinds)
|
|
|
78
83
|
: kind === 'settings-page'
|
|
79
84
|
? "Create ui/settings/page.tsx, which replaces the plugin's generated settings page."
|
|
80
85
|
: kind === 'layout'
|
|
81
|
-
? 'Create src/layouts/<
|
|
86
|
+
? 'Create a layout: src/layouts/<family>[/<variant>].tsx, or ui/layouts/... of a plugin.'
|
|
82
87
|
: kind === 'test'
|
|
83
88
|
? 'Create tests/<plugin>.test.ts, a headless test that mounts the plugin, and list what running it still needs.'
|
|
84
89
|
: `Create ${/^[aeiou]/.test(kind) ? 'an' : 'a'} ${kind} file. Its ID comes from the file path.`,
|
|
85
90
|
)
|
|
86
|
-
.action(async (target) => {
|
|
87
|
-
const result = await addContribution(kind, target);
|
|
91
|
+
.action(async (target, options) => {
|
|
92
|
+
const result = await addContribution(kind, target, { plugin: options?.plugin });
|
|
88
93
|
if (result.createdPlugin) console.log(`\nCreated plugin "${result.plugin}".`);
|
|
89
94
|
console.log(
|
|
90
95
|
kind === 'slot'
|
|
@@ -102,6 +107,7 @@ for (const kind of contributionKinds)
|
|
|
102
107
|
console.log(`\nRun it from the app root with ${result.run} (Node.js 24 or newer).`);
|
|
103
108
|
console.log('');
|
|
104
109
|
});
|
|
110
|
+
}
|
|
105
111
|
|
|
106
112
|
program
|
|
107
113
|
.command('init')
|
package/src/doctor.mjs
CHANGED
|
@@ -11,6 +11,7 @@ import {
|
|
|
11
11
|
import { checkAgentFiles } from './doctor-agent-files.mjs';
|
|
12
12
|
import { exists, findProject } from './project.mjs';
|
|
13
13
|
import { appRoutes, catchAllRoute, rootLayouts, shellGroup } from './routes.mjs';
|
|
14
|
+
import { describeSlots } from './slots.mjs';
|
|
14
15
|
|
|
15
16
|
/**
|
|
16
17
|
* Checks a project for the problems that most often break a BitaKit app: mixed package
|
|
@@ -97,6 +98,7 @@ export async function doctor({ cwd } = {}) {
|
|
|
97
98
|
results.push(await checkStyles(project, description));
|
|
98
99
|
results.push(...(await checkTailwind(project, description)));
|
|
99
100
|
results.push(checkIgnored(description), checkDeprecated(description), checkSlots(description));
|
|
101
|
+
results.push(await checkParts(description));
|
|
100
102
|
if (shell) {
|
|
101
103
|
const missing = [];
|
|
102
104
|
for (const module of modules)
|
|
@@ -259,10 +261,10 @@ async function checkWiring(project) {
|
|
|
259
261
|
fix: 'Run "npx bitakit migrate", or rename withFoundation to withBitaKit.',
|
|
260
262
|
}
|
|
261
263
|
: {
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
264
|
+
status: 'error',
|
|
265
|
+
title: 'next.config does not run BitaKit discovery',
|
|
266
|
+
fix: "import { withBitaKit } from '@bitakit/next/config';\nexport default withBitaKit({});",
|
|
267
|
+
},
|
|
266
268
|
);
|
|
267
269
|
const scripts = JSON.stringify(project.manifest.scripts ?? {});
|
|
268
270
|
if (scripts.includes('--webpack'))
|
|
@@ -290,10 +292,10 @@ async function checkWiring(project) {
|
|
|
290
292
|
fix: 'Run "npx bitakit migrate", or import { bitakit } from \'@bitakit/tanstack/config\' and call bitakit().',
|
|
291
293
|
}
|
|
292
294
|
: {
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
295
|
+
status: 'error',
|
|
296
|
+
title: 'vite.config does not run BitaKit discovery',
|
|
297
|
+
fix: "import { bitakit } from '@bitakit/tanstack/config';\nplugins: [bitakit(), tanstackStart(), ...]",
|
|
298
|
+
},
|
|
297
299
|
);
|
|
298
300
|
}
|
|
299
301
|
let provider = false;
|
|
@@ -357,7 +359,8 @@ async function mountsProvider(file, root, seen = new Set()) {
|
|
|
357
359
|
// The generated file exports BitaKitProvider; the packages export BitaKitRuntimeProvider.
|
|
358
360
|
if (
|
|
359
361
|
(entry.name === 'BitaKitProvider' && /bitakit\.gen$/.test(entry.from)) ||
|
|
360
|
-
(entry.name === 'BitaKitRuntimeProvider' &&
|
|
362
|
+
(entry.name === 'BitaKitRuntimeProvider' &&
|
|
363
|
+
/^@bitakit\/(?:ui|next|tanstack)$/.test(entry.from))
|
|
361
364
|
)
|
|
362
365
|
return true;
|
|
363
366
|
const base = entry.from.startsWith('@/')
|
|
@@ -460,12 +463,12 @@ async function providedKeys(root, entries) {
|
|
|
460
463
|
node.expression.name.text === 'of'
|
|
461
464
|
? nameOf(node.expression.expression)
|
|
462
465
|
: ts.isCallExpression(node) &&
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
466
|
+
ts.isIdentifier(node.expression) &&
|
|
467
|
+
['serviceKey', 'defineContract'].includes(node.expression.text) &&
|
|
468
|
+
node.arguments[0] &&
|
|
469
|
+
ts.isStringLiteralLike(node.arguments[0])
|
|
470
|
+
? node.arguments[0].text
|
|
471
|
+
: undefined;
|
|
469
472
|
const visit = (node) => {
|
|
470
473
|
if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
|
|
471
474
|
const name = nameOf(node.initializer);
|
|
@@ -911,6 +914,38 @@ function checkSlots(description) {
|
|
|
911
914
|
fix: 'Declare the owner contract with defineSlot in slots/. ui/slots/ contributes components; Action slots must reference declared action contracts. Legacy bitakit.config.ts slots are name hints only.',
|
|
912
915
|
};
|
|
913
916
|
}
|
|
917
|
+
/**
|
|
918
|
+
* Replaceable (`single`) slots: every `choose` entry names one, and no part has several
|
|
919
|
+
* candidates in the app's files without a decision. Packages add candidates only at runtime.
|
|
920
|
+
*/
|
|
921
|
+
async function checkParts(description) {
|
|
922
|
+
const { slots } = await describeSlots(description);
|
|
923
|
+
const byId = new Map(slots.map((slot) => [slot.id, slot]));
|
|
924
|
+
const problems = [];
|
|
925
|
+
for (const [id, choice] of Object.entries(description.choose ?? {})) {
|
|
926
|
+
const slot = byId.get(id);
|
|
927
|
+
if (!slot)
|
|
928
|
+
problems.push(
|
|
929
|
+
`bitakit.config.ts chooses "${choice}" for "${id}", but no slot "${id}" exists.`,
|
|
930
|
+
);
|
|
931
|
+
else if (slot.policy && slot.policy !== 'single')
|
|
932
|
+
problems.push(
|
|
933
|
+
`bitakit.config.ts chooses "${choice}" for "${id}", a ${slot.policy} slot; choose applies to single slots only.`,
|
|
934
|
+
);
|
|
935
|
+
}
|
|
936
|
+
for (const slot of slots)
|
|
937
|
+
if (slot.selection?.reason === 'ambiguous')
|
|
938
|
+
problems.push(
|
|
939
|
+
`"${slot.id}" has several candidates (${slot.selection.candidates.join(', ')}) and renders its default.`,
|
|
940
|
+
);
|
|
941
|
+
if (!problems.length) return { status: 'ok', title: 'Replaceable parts are decided' };
|
|
942
|
+
return {
|
|
943
|
+
status: 'warn',
|
|
944
|
+
title: `${plural(problems.length, 'replaceable part')} need${problems.length === 1 ? 's' : ''} a decision`,
|
|
945
|
+
details: problems,
|
|
946
|
+
fix: "Pick one per slot in bitakit.config.ts, for example choose: { 'layout.auth': 'split' }, or keep a single candidate. The app's own file wins over plugins without configuration.",
|
|
947
|
+
};
|
|
948
|
+
}
|
|
914
949
|
function checkDeprecated(description) {
|
|
915
950
|
const deprecated = description.warnings.filter(isDeprecation);
|
|
916
951
|
if (!deprecated.length) return { status: 'ok', title: 'Folder layout is current' };
|
package/src/project.mjs
CHANGED
|
@@ -52,7 +52,10 @@ async function describeProject(root, manifest) {
|
|
|
52
52
|
let configError;
|
|
53
53
|
try {
|
|
54
54
|
// The CLI still reads the 0.1 file so doctor and migrate can report what it needs.
|
|
55
|
-
loaded = await loadDiscoveryConfig(root, undefined, [
|
|
55
|
+
loaded = await loadDiscoveryConfig(root, undefined, [
|
|
56
|
+
'bitakit.config.ts',
|
|
57
|
+
'foundation.config.ts',
|
|
58
|
+
]);
|
|
56
59
|
} catch (error) {
|
|
57
60
|
configError = error;
|
|
58
61
|
const legacy =
|