@bitakit/cli 0.2.5 → 0.2.7
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 +37 -0
- package/CLAUDE.md +1 -0
- package/README.md +14 -2
- package/package.json +5 -3
- package/skills/bitakit-app-development/README.md +27 -14
- package/skills/bitakit-app-development/SKILL.md +100 -69
- package/skills/bitakit-app-development/references/actions.md +2 -1
- package/skills/bitakit-app-development/references/best-practices.md +214 -0
- package/skills/bitakit-app-development/references/create-app.md +57 -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/plugin-guides.md +63 -0
- package/skills/bitakit-app-development/references/plugins-and-pages.md +11 -12
- package/skills/bitakit-app-development/references/slots.md +26 -17
- package/skills/bitakit-app-development/references/testing-and-preview.md +12 -9
- package/skills/bitakit-app-development/references/worked-example.md +312 -0
- package/src/add.mjs +45 -12
- package/src/agent-rules.mjs +45 -3
- package/src/cli.mjs +14 -8
- package/src/doctor.mjs +34 -0
- package/src/slots.mjs +55 -1
- package/src/templates.mjs +9 -6
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)
|
|
@@ -912,6 +914,38 @@ function checkSlots(description) {
|
|
|
912
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.',
|
|
913
915
|
};
|
|
914
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
|
+
}
|
|
915
949
|
function checkDeprecated(description) {
|
|
916
950
|
const deprecated = description.warnings.filter(isDeprecation);
|
|
917
951
|
if (!deprecated.length) return { status: 'ok', title: 'Folder layout is current' };
|
package/src/slots.mjs
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import path from 'node:path';
|
|
2
|
+
import { candidateNames, selectSingle } from '@bitakit/core';
|
|
2
3
|
import { describeDefinitions } from '@bitakit/discovery';
|
|
3
4
|
|
|
4
5
|
const objectHelpers = new Set(['object', 'strictObject', 'looseObject']);
|
|
@@ -102,6 +103,15 @@ export async function describeSlots(description) {
|
|
|
102
103
|
plugin: module.id,
|
|
103
104
|
source: entry.file,
|
|
104
105
|
});
|
|
106
|
+
// Layout files are candidates for layout.<family>, keyed by their variant.
|
|
107
|
+
for (const entry of module.layouts ?? [])
|
|
108
|
+
contribute(`layout.${entry.family}`, {
|
|
109
|
+
kind: 'component',
|
|
110
|
+
id: null,
|
|
111
|
+
plugin: module.id,
|
|
112
|
+
key: entry.variant,
|
|
113
|
+
source: entry.file,
|
|
114
|
+
});
|
|
105
115
|
const actions = await describeDefinitions(absolute(module.actions), {
|
|
106
116
|
helper: 'defineAction',
|
|
107
117
|
moduleId: moduleId(module),
|
|
@@ -144,6 +154,24 @@ export async function describeSlots(description) {
|
|
|
144
154
|
};
|
|
145
155
|
});
|
|
146
156
|
const declared = new Set(slots.map((slot) => slot.id));
|
|
157
|
+
// Discovery declares layout families nobody else declares as app-owned single slots.
|
|
158
|
+
for (const [id, entries] of contributions)
|
|
159
|
+
if (id.startsWith('layout.') && !declared.has(id) && entries.some((entry) => entry.key)) {
|
|
160
|
+
declared.add(id);
|
|
161
|
+
slots.push({
|
|
162
|
+
id,
|
|
163
|
+
owner: description.app.id,
|
|
164
|
+
plugin: description.app.id,
|
|
165
|
+
contract: true,
|
|
166
|
+
accepts: 'component',
|
|
167
|
+
policy: 'single',
|
|
168
|
+
payload: false,
|
|
169
|
+
payloadKeys: [],
|
|
170
|
+
source: entries[0].source,
|
|
171
|
+
generated: true,
|
|
172
|
+
contributions: entries,
|
|
173
|
+
});
|
|
174
|
+
}
|
|
147
175
|
for (const id of description.slots ?? [])
|
|
148
176
|
if (!declared.has(id)) {
|
|
149
177
|
declared.add(id);
|
|
@@ -171,6 +199,23 @@ export async function describeSlots(description) {
|
|
|
171
199
|
const index = slot.contract ? order.indexOf(slot.owner) : -1;
|
|
172
200
|
return index >= 0 ? index : order.length + (slot.contract ? 0 : 1);
|
|
173
201
|
};
|
|
202
|
+
// A single slot renders one candidate: report which, by the runtime's own rules, from files.
|
|
203
|
+
for (const slot of slots)
|
|
204
|
+
if (slot.policy === 'single') {
|
|
205
|
+
const candidates = slot.contributions.filter((entry) => entry.kind === 'component');
|
|
206
|
+
const selection = selectSingle(candidates, {
|
|
207
|
+
choice: description.choose?.[slot.id],
|
|
208
|
+
appId: description.app.id,
|
|
209
|
+
});
|
|
210
|
+
slot.selection = {
|
|
211
|
+
candidates: candidates.map((entry) => candidateNames(entry)[1] ?? entry.plugin),
|
|
212
|
+
renders: selection.selected
|
|
213
|
+
? (candidateNames(selection.selected)[1] ?? selection.selected.plugin)
|
|
214
|
+
: null,
|
|
215
|
+
reason: selection.reason ?? null,
|
|
216
|
+
choice: description.choose?.[slot.id] ?? null,
|
|
217
|
+
};
|
|
218
|
+
}
|
|
174
219
|
return {
|
|
175
220
|
version: 1,
|
|
176
221
|
slots: slots
|
|
@@ -182,6 +227,15 @@ export async function describeSlots(description) {
|
|
|
182
227
|
};
|
|
183
228
|
}
|
|
184
229
|
|
|
230
|
+
/** One replaceable part: which candidate renders, or why the owner's default does. */
|
|
231
|
+
function selectionText({ renders, reason, candidates }) {
|
|
232
|
+
if (renders) return `renders ${renders}`;
|
|
233
|
+
if (reason === 'ambiguous')
|
|
234
|
+
return `renders the default: choose one of ${candidates.join(', ')} in bitakit.config.ts`;
|
|
235
|
+
if (reason === 'choice-unavailable') return 'renders the default: choose names no candidate';
|
|
236
|
+
return 'renders the default';
|
|
237
|
+
}
|
|
238
|
+
|
|
185
239
|
/** The short human listing: one line per slot under its owner. */
|
|
186
240
|
export function formatSlots(result, { dim = (text) => text } = {}) {
|
|
187
241
|
const lines = result.slots.length ? [] : ['No slots are declared.'];
|
|
@@ -197,7 +251,7 @@ export function formatSlots(result, { dim = (text) => text } = {}) {
|
|
|
197
251
|
if (title !== group) lines.push('', title);
|
|
198
252
|
group = title;
|
|
199
253
|
lines.push(
|
|
200
|
-
` ${slot.id.padEnd(width)} ${(slot.accepts ?? 'unknown').padEnd(9)} ${plural(slot.contributions.length, 'contribution')}`,
|
|
254
|
+
` ${slot.id.padEnd(width)} ${(slot.accepts ?? 'unknown').padEnd(9)} ${plural(slot.contributions.length, 'contribution')}${slot.selection ? ` ${selectionText(slot.selection)}` : ''}`,
|
|
201
255
|
);
|
|
202
256
|
}
|
|
203
257
|
if (result.slots.length)
|
package/src/templates.mjs
CHANGED
|
@@ -443,12 +443,14 @@ export default defineSettings({
|
|
|
443
443
|
`;
|
|
444
444
|
}
|
|
445
445
|
|
|
446
|
-
export function layoutFile(
|
|
447
|
-
const component = `${pascalOf(
|
|
446
|
+
export function layoutFile(family, variant) {
|
|
447
|
+
const component = `${pascalOf(variant === undefined ? family : `${family}-${variant}`)}Layout`;
|
|
448
448
|
return `import type { ReactNode } from 'react';
|
|
449
449
|
|
|
450
|
-
//
|
|
451
|
-
export
|
|
450
|
+
// A candidate for the layout.${family} slot. Pages choose the family with:
|
|
451
|
+
// export const layout = '${family}';
|
|
452
|
+
// With several candidates, pick one in bitakit.config.ts: choose: { 'layout.${family}': '${variant ?? 'default'}' }
|
|
453
|
+
export default function ${component}({ children }: { children?: ReactNode }) {
|
|
452
454
|
return <div className="mx-auto flex w-full max-w-6xl flex-1 flex-col gap-6 p-4 md:p-6">{children}</div>;
|
|
453
455
|
}
|
|
454
456
|
`;
|
|
@@ -458,8 +460,9 @@ export function slotFile(plugin, slot) {
|
|
|
458
460
|
const component = `${pascalOf(slot.replace(/\./g, '-'))}Slot`;
|
|
459
461
|
return `'use client';
|
|
460
462
|
|
|
461
|
-
// A
|
|
462
|
-
//
|
|
463
|
+
// A contribution to the "${slot}" slot; its owner renders it with <PluginSlot name="${slot}" />.
|
|
464
|
+
// In a list slot it appears next to the others (export const order = 1 sorts them). In a single
|
|
465
|
+
// slot, a replaceable part such as screen.not-found, it replaces the owner's default.
|
|
463
466
|
export default function ${component}() {
|
|
464
467
|
return <span className="text-sm text-muted-foreground">${plugin}</span>;
|
|
465
468
|
}
|