@bitakit/cli 0.2.1 → 0.2.2
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 +128 -11
- package/package.json +4 -3
- package/skills/bitakit-app-development/README.md +121 -0
- package/skills/bitakit-app-development/SKILL.md +144 -0
- package/skills/bitakit-app-development/references/actions.md +198 -0
- package/skills/bitakit-app-development/references/interceptors.md +164 -0
- package/skills/bitakit-app-development/references/plugins-and-pages.md +165 -0
- package/skills/bitakit-app-development/references/services-and-events.md +173 -0
- package/skills/bitakit-app-development/references/settings.md +183 -0
- package/skills/bitakit-app-development/references/slots.md +165 -0
- package/skills/bitakit-app-development/references/testing-and-preview.md +171 -0
- package/src/add.mjs +96 -4
- package/src/agent-rules.mjs +42 -3
- package/src/agent-skill.mjs +152 -0
- package/src/check-page.mjs +385 -0
- package/src/cli.mjs +109 -18
- package/src/doctor-agent-files.mjs +66 -0
- package/src/doctor.mjs +5 -2
- package/src/index.mjs +9 -0
- package/src/init.mjs +65 -21
- package/src/slots.mjs +227 -0
- package/src/templates.mjs +86 -45
package/src/index.mjs
CHANGED
|
@@ -6,7 +6,15 @@ export {
|
|
|
6
6
|
agentRulesEnd,
|
|
7
7
|
bitakitIdentity,
|
|
8
8
|
claudeFileFor,
|
|
9
|
+
projectAgentRules,
|
|
10
|
+
refreshAgentRules,
|
|
9
11
|
} from './agent-rules.mjs';
|
|
12
|
+
export {
|
|
13
|
+
appDevelopmentSkillPaths,
|
|
14
|
+
bundledSkillFiles,
|
|
15
|
+
readSkillFiles,
|
|
16
|
+
writeAppDevelopmentSkills,
|
|
17
|
+
} from './agent-skill.mjs';
|
|
10
18
|
export { buildPlugin } from './build.mjs';
|
|
11
19
|
export { doctor } from './doctor.mjs';
|
|
12
20
|
export {
|
|
@@ -20,6 +28,7 @@ export {
|
|
|
20
28
|
} from './init.mjs';
|
|
21
29
|
export { findProject, findProjectRoot, packagePluginId } from './project.mjs';
|
|
22
30
|
export { appRoutes, catchAllRoute } from './routes.mjs';
|
|
31
|
+
export { describeSlots, formatSlots } from './slots.mjs';
|
|
23
32
|
export {
|
|
24
33
|
actionFile,
|
|
25
34
|
configFile,
|
package/src/init.mjs
CHANGED
|
@@ -1,7 +1,13 @@
|
|
|
1
1
|
import { mkdir, readFile, writeFile } from 'node:fs/promises';
|
|
2
2
|
import path from 'node:path';
|
|
3
3
|
import ts from 'typescript';
|
|
4
|
-
import {
|
|
4
|
+
import {
|
|
5
|
+
agentRulesBegin,
|
|
6
|
+
claudeFileFor,
|
|
7
|
+
projectAgentRules,
|
|
8
|
+
refreshAgentRules,
|
|
9
|
+
} from './agent-rules.mjs';
|
|
10
|
+
import { cliVersion, writeAppDevelopmentSkills } from './agent-skill.mjs';
|
|
5
11
|
import { exists, findProject } from './project.mjs';
|
|
6
12
|
import { appRoutes, catchAllRoute, rootLayouts, shellGroup } from './routes.mjs';
|
|
7
13
|
|
|
@@ -121,11 +127,14 @@ function wrapLayout(source, fileName, specifier, framework) {
|
|
|
121
127
|
* Vite plugin, the provider in the root layout, the catch-all route for plugin pages, the
|
|
122
128
|
* `.gitignore` entry and the agent rules in `AGENTS.md` (the same block create-app writes), which
|
|
123
129
|
* `CLAUDE.md` imports.
|
|
124
|
-
* Files that already carry the wiring are never touched.
|
|
125
|
-
*
|
|
126
|
-
*
|
|
130
|
+
* Files that already carry the wiring are never touched. With `updateAgentFiles`, the BitaKit
|
|
131
|
+
* block of `AGENTS.md` is replaced with the current rules and unedited skill copies are updated
|
|
132
|
+
* (see `writeAppDevelopmentSkills`); edited copies are kept.
|
|
133
|
+
* Returns `written` (absolute paths; `created` is false for an edited file; `note` says what an
|
|
134
|
+
* update changed), `skipped` with the reason for each, and the BitaKit packages the app still has
|
|
135
|
+
* to install.
|
|
127
136
|
*/
|
|
128
|
-
export async function initProject({ cwd } = {}) {
|
|
137
|
+
export async function initProject({ cwd, updateAgentFiles = false } = {}) {
|
|
129
138
|
const project = await findProject(cwd);
|
|
130
139
|
if (project.kind !== 'app') throw new Error('Run "bitakit init" inside an app.');
|
|
131
140
|
if (!project.framework)
|
|
@@ -139,10 +148,10 @@ export async function initProject({ cwd } = {}) {
|
|
|
139
148
|
const first = async (files) => {
|
|
140
149
|
for (const file of files) if (await exists(file)) return file;
|
|
141
150
|
};
|
|
142
|
-
const put = async (file, content, created = false) => {
|
|
151
|
+
const put = async (file, content, created = false, note) => {
|
|
143
152
|
await mkdir(path.dirname(file), { recursive: true });
|
|
144
153
|
await writeFile(file, content);
|
|
145
|
-
written.push({ file, created });
|
|
154
|
+
written.push(note ? { file, created, note } : { file, created });
|
|
146
155
|
};
|
|
147
156
|
const skip = (file, reason) => skipped.push({ file, reason });
|
|
148
157
|
|
|
@@ -228,34 +237,69 @@ export async function initProject({ cwd } = {}) {
|
|
|
228
237
|
);
|
|
229
238
|
|
|
230
239
|
const dependencies = { ...project.manifest.dependencies, ...project.manifest.devDependencies };
|
|
231
|
-
const
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
project.framework === 'next'
|
|
237
|
-
? (await exists(at('src/app')))
|
|
238
|
-
? 'src/app'
|
|
239
|
-
: 'app'
|
|
240
|
-
: 'src/routes';
|
|
241
|
-
const rules = agentRules({ routes, shell: Boolean(dependencies['@bitakit/shell']) });
|
|
240
|
+
const agentsFile = at('AGENTS.md');
|
|
241
|
+
const agents = await read(agentsFile);
|
|
242
|
+
const rules = await projectAgentRules(project);
|
|
243
|
+
const refreshed = refreshAgentRules(agents, rules);
|
|
244
|
+
if (!agents?.includes(agentRulesBegin))
|
|
242
245
|
await put(
|
|
243
|
-
|
|
246
|
+
agentsFile,
|
|
244
247
|
agents === undefined ? rules : `${agents.trimEnd()}\n\n${rules}`,
|
|
245
248
|
agents === undefined,
|
|
246
249
|
);
|
|
247
|
-
|
|
250
|
+
else if (refreshed === agents)
|
|
251
|
+
skip(
|
|
252
|
+
agentsFile,
|
|
253
|
+
updateAgentFiles ? 'the BitaKit rules are up to date' : 'already has the BitaKit rules',
|
|
254
|
+
);
|
|
255
|
+
else if (refreshed === undefined)
|
|
256
|
+
skip(agentsFile, 'the BitaKit block has no end marker; restore it by hand');
|
|
257
|
+
else if (!updateAgentFiles)
|
|
258
|
+
skip(agentsFile, 'already has the BitaKit rules; --update-agent-files refreshes them');
|
|
259
|
+
else await put(agentsFile, refreshed, false, 'refreshed the BitaKit rules');
|
|
248
260
|
// Claude Code loads CLAUDE.md, so it imports the rules; an existing file only gets the import line.
|
|
249
261
|
const claudeFile = at('CLAUDE.md');
|
|
250
262
|
const claude = await read(claudeFile);
|
|
251
263
|
const claudeNext = claudeFileFor(claude);
|
|
252
264
|
if (claudeNext === claude) skip(claudeFile, 'already imports AGENTS.md');
|
|
253
265
|
else await put(claudeFile, claudeNext, claude === undefined);
|
|
266
|
+
|
|
267
|
+
for (const skill of await writeAppDevelopmentSkills(project.root, {
|
|
268
|
+
update: updateAgentFiles,
|
|
269
|
+
})) {
|
|
270
|
+
if (skill.change === 'installed') written.push({ file: skill.file, created: true });
|
|
271
|
+
else if (skill.change)
|
|
272
|
+
written.push({
|
|
273
|
+
file: skill.file,
|
|
274
|
+
created: false,
|
|
275
|
+
note:
|
|
276
|
+
skill.change === 'updated'
|
|
277
|
+
? `updated from ${skill.version}`
|
|
278
|
+
: `up to date; stamped with ${cliVersion}`,
|
|
279
|
+
});
|
|
280
|
+
else skip(skill.file, skillReason(skill, updateAgentFiles));
|
|
281
|
+
}
|
|
282
|
+
|
|
254
283
|
const install = [
|
|
255
284
|
'@bitakit/core',
|
|
256
285
|
'@bitakit/discovery',
|
|
257
286
|
'@bitakit/ui',
|
|
258
287
|
project.framework === 'next' ? '@bitakit/next' : '@bitakit/tanstack',
|
|
259
288
|
].filter((name) => !dependencies[name]);
|
|
260
|
-
|
|
289
|
+
// The rules and the skill tell agents to run `npx bitakit ...`, which needs the local CLI; a
|
|
290
|
+
// one-off `npx @bitakit/cli init` does not install it.
|
|
291
|
+
const installDev = ['@bitakit/cli'].filter((name) => !dependencies[name]);
|
|
292
|
+
return { project, written, skipped, install, installDev };
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
/** Why `init` left an existing skill copy alone. */
|
|
296
|
+
function skillReason(skill, update) {
|
|
297
|
+
if (!update)
|
|
298
|
+
return skill.state === 'outdated'
|
|
299
|
+
? `already exists; preserved; --update-agent-files updates it from ${skill.version} to ${cliVersion}`
|
|
300
|
+
: 'already exists; preserved';
|
|
301
|
+
if (skill.state === 'current') return 'up to date';
|
|
302
|
+
if (skill.state === 'newer')
|
|
303
|
+
return `from @bitakit/cli ${skill.version}, newer than this CLI; kept`;
|
|
304
|
+
return `edited locally; kept. Delete its folder and run again to get ${cliVersion}`;
|
|
261
305
|
}
|
package/src/slots.mjs
ADDED
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
import path from 'node:path';
|
|
2
|
+
import { describeDefinitions } from '@bitakit/discovery';
|
|
3
|
+
|
|
4
|
+
const objectHelpers = new Set(['object', 'strictObject', 'looseObject']);
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Keys of a `z.object({ ... })`/`v.object({ ... })` payload; any other schema keeps them unknown.
|
|
8
|
+
* Nodes come from discovery's parser, so they are classified with its `ts`, not a local import.
|
|
9
|
+
*/
|
|
10
|
+
function payloadOf(fields, { unwrap, ts }) {
|
|
11
|
+
if (!fields.has('payload')) return { payload: false, payloadKeys: [] };
|
|
12
|
+
const schema = unwrap(fields.get('payload'));
|
|
13
|
+
const callee =
|
|
14
|
+
schema && ts.isCallExpression(schema)
|
|
15
|
+
? ts.isPropertyAccessExpression(schema.expression)
|
|
16
|
+
? schema.expression.name.text
|
|
17
|
+
: ts.isIdentifier(schema.expression) && schema.expression.text
|
|
18
|
+
: undefined;
|
|
19
|
+
const shape = objectHelpers.has(callee) ? unwrap(schema.arguments[0]) : undefined;
|
|
20
|
+
if (!shape || !ts.isObjectLiteralExpression(shape)) return { payload: true, payloadKeys: null };
|
|
21
|
+
const keys = [];
|
|
22
|
+
for (const item of shape.properties) {
|
|
23
|
+
if (!item.name || ts.isComputedPropertyName(item.name))
|
|
24
|
+
return { payload: true, payloadKeys: null };
|
|
25
|
+
keys.push(item.name.text);
|
|
26
|
+
}
|
|
27
|
+
return { payload: true, payloadKeys: keys };
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* Slot names of an Action's literal `slots` list; `resolved` is false when any entry is not
|
|
32
|
+
* literal.
|
|
33
|
+
*/
|
|
34
|
+
function placementsOf(fields, { unwrap, literal, ts }) {
|
|
35
|
+
if (!fields.has('slots')) return { placements: [], resolved: true };
|
|
36
|
+
const list = unwrap(fields.get('slots'));
|
|
37
|
+
if (!list || !ts.isArrayLiteralExpression(list)) return { placements: [], resolved: false };
|
|
38
|
+
const placements = [];
|
|
39
|
+
let resolved = true;
|
|
40
|
+
for (const element of list.elements) {
|
|
41
|
+
const object = unwrap(element);
|
|
42
|
+
const slot =
|
|
43
|
+
object && ts.isObjectLiteralExpression(object)
|
|
44
|
+
? object.properties.find(
|
|
45
|
+
(item) =>
|
|
46
|
+
(ts.isPropertyAssignment(item) || ts.isShorthandPropertyAssignment(item)) &&
|
|
47
|
+
!ts.isComputedPropertyName(item.name) &&
|
|
48
|
+
item.name.text === 'slot',
|
|
49
|
+
)
|
|
50
|
+
: undefined;
|
|
51
|
+
const name = slot
|
|
52
|
+
? literal(ts.isPropertyAssignment(slot) ? slot.initializer : slot.name)
|
|
53
|
+
: literal(element);
|
|
54
|
+
if (name === undefined) resolved = false;
|
|
55
|
+
else placements.push(name);
|
|
56
|
+
}
|
|
57
|
+
return { placements, resolved };
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
const plural = (count, word) => `${count} ${word}${count === 1 ? '' : 's'}`;
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Every slot the app knows, answering "where can I put this?": the owned contracts of the app,
|
|
64
|
+
* its enabled plugins and installed packages (their derived `*.slots.json`), plus name hints from
|
|
65
|
+
* package manifests and `bitakit.config.ts`; the same set doctor counts. Contributions come from
|
|
66
|
+
* the app's own files only: `ui/slots` components and Actions whose literal `slots` place them.
|
|
67
|
+
* Packages and `setup()` attach more at runtime. Nothing is executed; a field a file does not
|
|
68
|
+
* state literally is `null` (unknown), and files that could not be read are listed in `unresolved`.
|
|
69
|
+
* Contributions to IDs that are neither declared nor hinted are listed in `unknownTargets`.
|
|
70
|
+
*/
|
|
71
|
+
export async function describeSlots(description) {
|
|
72
|
+
const modules = [
|
|
73
|
+
description.app,
|
|
74
|
+
...description.plugins.filter((plugin) => plugin.enabled !== false),
|
|
75
|
+
];
|
|
76
|
+
const absolute = (entries) =>
|
|
77
|
+
(entries ?? []).map((entry) => ({ ...entry, file: path.join(description.root, entry.file) }));
|
|
78
|
+
const relative = (file) => path.relative(description.root, file).split(path.sep).join('/');
|
|
79
|
+
const moduleId = (module) => (module === description.app ? '' : module.id);
|
|
80
|
+
const unresolved = new Set(description.unresolvedSlots ?? []);
|
|
81
|
+
|
|
82
|
+
const owners = new Map();
|
|
83
|
+
const payloads = new Map();
|
|
84
|
+
for (const module of modules) {
|
|
85
|
+
for (const entry of module.slotDefinitions ?? []) owners.set(entry.file, module.id);
|
|
86
|
+
const { definitions } = await describeDefinitions(absolute(module.slotDefinitions), {
|
|
87
|
+
helper: 'defineSlot',
|
|
88
|
+
moduleId: moduleId(module),
|
|
89
|
+
inspect: payloadOf,
|
|
90
|
+
});
|
|
91
|
+
for (const item of definitions) payloads.set(`${relative(item.file)}\0${item.id}`, item);
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
const contributions = new Map();
|
|
95
|
+
const contribute = (slot, entry) =>
|
|
96
|
+
contributions.set(slot, [...(contributions.get(slot) ?? []), entry]);
|
|
97
|
+
for (const module of modules) {
|
|
98
|
+
for (const entry of module.slots ?? [])
|
|
99
|
+
contribute(entry.path, {
|
|
100
|
+
kind: 'component',
|
|
101
|
+
id: null,
|
|
102
|
+
plugin: module.id,
|
|
103
|
+
source: entry.file,
|
|
104
|
+
});
|
|
105
|
+
const actions = await describeDefinitions(absolute(module.actions), {
|
|
106
|
+
helper: 'defineAction',
|
|
107
|
+
moduleId: moduleId(module),
|
|
108
|
+
inspect: placementsOf,
|
|
109
|
+
});
|
|
110
|
+
actions.unresolved.forEach((file) => unresolved.add(relative(file)));
|
|
111
|
+
for (const action of actions.definitions) {
|
|
112
|
+
if (!action.resolved) unresolved.add(relative(action.file));
|
|
113
|
+
for (const slot of new Set(action.placements))
|
|
114
|
+
contribute(slot, {
|
|
115
|
+
kind: 'action',
|
|
116
|
+
id: action.id,
|
|
117
|
+
plugin: module.id,
|
|
118
|
+
source: relative(action.file),
|
|
119
|
+
});
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
const slots = (description.slotDeclarations ?? []).map((declaration) => {
|
|
124
|
+
const local = owners.get(declaration.file);
|
|
125
|
+
const details = payloads.get(`${declaration.file}\0${declaration.id}`);
|
|
126
|
+
return {
|
|
127
|
+
id: declaration.id,
|
|
128
|
+
owner:
|
|
129
|
+
local ??
|
|
130
|
+
(description.installedPackages ?? []).find((name) =>
|
|
131
|
+
declaration.file.startsWith(`${name}/`),
|
|
132
|
+
) ??
|
|
133
|
+
declaration.plugin ??
|
|
134
|
+
null,
|
|
135
|
+
plugin: declaration.plugin ?? null,
|
|
136
|
+
contract: true,
|
|
137
|
+
accepts: declaration.accepts ?? null,
|
|
138
|
+
policy: declaration.policy ?? null,
|
|
139
|
+
// Package sidecars carry no payload description.
|
|
140
|
+
payload: local !== undefined && details ? details.payload : null,
|
|
141
|
+
payloadKeys: local !== undefined && details ? details.payloadKeys : null,
|
|
142
|
+
source: local !== undefined ? declaration.file : null,
|
|
143
|
+
contributions: contributions.get(declaration.id) ?? [],
|
|
144
|
+
};
|
|
145
|
+
});
|
|
146
|
+
const declared = new Set(slots.map((slot) => slot.id));
|
|
147
|
+
for (const id of description.slots ?? [])
|
|
148
|
+
if (!declared.has(id)) {
|
|
149
|
+
declared.add(id);
|
|
150
|
+
slots.push({
|
|
151
|
+
id,
|
|
152
|
+
owner: null,
|
|
153
|
+
plugin: null,
|
|
154
|
+
contract: false,
|
|
155
|
+
accepts: null,
|
|
156
|
+
policy: null,
|
|
157
|
+
payload: null,
|
|
158
|
+
payloadKeys: null,
|
|
159
|
+
source: null,
|
|
160
|
+
contributions: contributions.get(id) ?? [],
|
|
161
|
+
});
|
|
162
|
+
}
|
|
163
|
+
// A placement on a slot nobody declares renders nowhere; list it instead of dropping it.
|
|
164
|
+
const unknownTargets = [...contributions]
|
|
165
|
+
.filter(([slot]) => !declared.has(slot))
|
|
166
|
+
.flatMap(([slot, entries]) => entries.map((entry) => ({ slot, ...entry })));
|
|
167
|
+
|
|
168
|
+
// Group the app and its plugins first, then packages, then contract-less name hints.
|
|
169
|
+
const order = [...modules.map((module) => module.id), ...(description.installedPackages ?? [])];
|
|
170
|
+
const rank = (slot) => {
|
|
171
|
+
const index = slot.contract ? order.indexOf(slot.owner) : -1;
|
|
172
|
+
return index >= 0 ? index : order.length + (slot.contract ? 0 : 1);
|
|
173
|
+
};
|
|
174
|
+
return {
|
|
175
|
+
version: 1,
|
|
176
|
+
slots: slots
|
|
177
|
+
.map((slot, index) => ({ slot, index }))
|
|
178
|
+
.sort((a, b) => rank(a.slot) - rank(b.slot) || a.index - b.index)
|
|
179
|
+
.map(({ slot }) => slot),
|
|
180
|
+
unresolved: [...unresolved],
|
|
181
|
+
unknownTargets,
|
|
182
|
+
};
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
/** The short human listing: one line per slot under its owner. */
|
|
186
|
+
export function formatSlots(result, { dim = (text) => text } = {}) {
|
|
187
|
+
const lines = result.slots.length ? [] : ['No slots are declared.'];
|
|
188
|
+
const width = Math.max(0, ...result.slots.map((slot) => slot.id.length));
|
|
189
|
+
let group;
|
|
190
|
+
for (const slot of result.slots) {
|
|
191
|
+
// Only local declarations have a source file in the app.
|
|
192
|
+
const title = !slot.contract
|
|
193
|
+
? 'Name hints without a slot contract'
|
|
194
|
+
: slot.source
|
|
195
|
+
? `Plugin "${slot.owner}"`
|
|
196
|
+
: `Package "${slot.owner}"`;
|
|
197
|
+
if (title !== group) lines.push('', title);
|
|
198
|
+
group = title;
|
|
199
|
+
lines.push(
|
|
200
|
+
` ${slot.id.padEnd(width)} ${(slot.accepts ?? 'unknown').padEnd(9)} ${plural(slot.contributions.length, 'contribution')}`,
|
|
201
|
+
);
|
|
202
|
+
}
|
|
203
|
+
if (result.slots.length)
|
|
204
|
+
lines.push(
|
|
205
|
+
'',
|
|
206
|
+
dim(
|
|
207
|
+
"Contributions count this app's ui/slots files and Action slots; packages add theirs at runtime.",
|
|
208
|
+
),
|
|
209
|
+
dim('Payload keys, sources and contributors: npx bitakit slots --json'),
|
|
210
|
+
);
|
|
211
|
+
if (result.unknownTargets?.length)
|
|
212
|
+
lines.push(
|
|
213
|
+
'',
|
|
214
|
+
`${plural(result.unknownTargets.length, 'contribution')} to undeclared slots:`,
|
|
215
|
+
...result.unknownTargets.map(
|
|
216
|
+
(entry) =>
|
|
217
|
+
` ${entry.slot} ${entry.kind === 'action' ? `Action ${entry.id}` : 'component'} ${entry.source}`,
|
|
218
|
+
),
|
|
219
|
+
);
|
|
220
|
+
if (result.unresolved.length)
|
|
221
|
+
lines.push(
|
|
222
|
+
'',
|
|
223
|
+
`${plural(result.unresolved.length, 'file')} could not be read statically:`,
|
|
224
|
+
...result.unresolved.map((file) => ` ${file}`),
|
|
225
|
+
);
|
|
226
|
+
return lines;
|
|
227
|
+
}
|
package/src/templates.mjs
CHANGED
|
@@ -53,7 +53,7 @@ import { PageHeader } from '@bitakit/ui/components';
|
|
|
53
53
|
|
|
54
54
|
// Served at /${name}; the file's place under ui/pages is the URL.
|
|
55
55
|
// Grow the feature one file at a time:
|
|
56
|
-
// shared state -> npx bitakit add service ${name}
|
|
56
|
+
// shared state -> npx bitakit add service ${name}/<name> (starts as a counter store)
|
|
57
57
|
// a button -> npx bitakit add action ${name}/archive (bind it with <Action id="${name}.archive">)
|
|
58
58
|
export default function ${component}() {
|
|
59
59
|
return <PageHeader title="${title}" subtitle="Edit this page in src/plugins/${name}/ui/pages/index.tsx." />;
|
|
@@ -69,28 +69,28 @@ export default function ${component}() {
|
|
|
69
69
|
export function pluginFiles(name, { minimal = false, navigationSlot } = {}) {
|
|
70
70
|
validateName(name, 'plugin name');
|
|
71
71
|
const title = titleOf(name);
|
|
72
|
-
const
|
|
72
|
+
const list = `services${member(name)}.list`;
|
|
73
73
|
const files = {
|
|
74
|
-
'services/
|
|
74
|
+
'services/list.ts': `import { defineService } from '@bitakit/core';
|
|
75
75
|
|
|
76
|
-
export type
|
|
76
|
+
export type Entry = { id: number; title: string };
|
|
77
77
|
|
|
78
78
|
/**
|
|
79
|
-
* The ${title} plugin's data and behavior.
|
|
79
|
+
* The ${title} plugin's data and behavior. Entries live in memory, so a page reload starts
|
|
80
80
|
* empty. Replace the body with calls to your API or database when you are ready.
|
|
81
81
|
*/
|
|
82
82
|
export default defineService(({ store, events }) => {
|
|
83
83
|
// Observable state: actions and pages follow it without any wiring.
|
|
84
84
|
// Resources belong in onStart/onStop; Core awaits cleanup before replacement.
|
|
85
|
-
const state = store<{
|
|
85
|
+
const state = store<{ entries: Entry[] }>({ entries: [] });
|
|
86
86
|
return {
|
|
87
87
|
state,
|
|
88
88
|
add(title: string) {
|
|
89
|
-
state.set((s) => ({
|
|
89
|
+
state.set((s) => ({ entries: [...s.entries, { id: Date.now(), title: title.trim() }] }));
|
|
90
90
|
events.emit('${name}.changed', { kind: 'added' });
|
|
91
91
|
},
|
|
92
92
|
remove(id: number) {
|
|
93
|
-
state.set((s) => ({
|
|
93
|
+
state.set((s) => ({ entries: s.entries.filter((entry) => entry.id !== id) }));
|
|
94
94
|
events.emit('${name}.changed', { kind: 'removed' });
|
|
95
95
|
},
|
|
96
96
|
};
|
|
@@ -106,11 +106,11 @@ export default defineEvents({
|
|
|
106
106
|
'actions/add.ts': `import { defineAction } from '@bitakit/core';
|
|
107
107
|
|
|
108
108
|
export default defineAction<string>({
|
|
109
|
-
title: 'Add
|
|
109
|
+
title: 'Add entry',
|
|
110
110
|
// Buttons bound to this action are disabled while their input is empty.
|
|
111
111
|
enabled: ({ input }) => typeof input === 'string' && input.trim().length > 0,
|
|
112
112
|
// Runs when a bound button or your code executes "${name}.add".
|
|
113
|
-
execute: ({ services, input }) => ${
|
|
113
|
+
execute: ({ services, input }) => ${list}.add(input),
|
|
114
114
|
});
|
|
115
115
|
`,
|
|
116
116
|
};
|
|
@@ -123,20 +123,20 @@ export default defineAction<number>({
|
|
|
123
123
|
title: 'Remove',
|
|
124
124
|
// Each row tracks its own pending state.
|
|
125
125
|
concurrency: 'per-input',
|
|
126
|
-
execute: ({ services, input }) => ${
|
|
126
|
+
execute: ({ services, input }) => ${list}.remove(input),
|
|
127
127
|
});
|
|
128
128
|
`,
|
|
129
129
|
'actions/clear.ts': `import { defineAction } from '@bitakit/core';
|
|
130
130
|
|
|
131
131
|
export default defineAction({
|
|
132
132
|
title: 'Clear all',
|
|
133
|
-
// Re-evaluated whenever the
|
|
134
|
-
enabled: ({ services }) => ${
|
|
135
|
-
confirm: 'Remove all
|
|
133
|
+
// Re-evaluated whenever the list's store changes.
|
|
134
|
+
enabled: ({ services }) => ${list}.state.get().entries.length > 0,
|
|
135
|
+
confirm: 'Remove all entries?',
|
|
136
136
|
execute: ({ services }) => {
|
|
137
|
-
for (const
|
|
137
|
+
for (const entry of ${list}.state.get().entries) ${list}.remove(entry.id);
|
|
138
138
|
},
|
|
139
|
-
success: 'All
|
|
139
|
+
success: 'All entries removed',
|
|
140
140
|
});
|
|
141
141
|
`,
|
|
142
142
|
'actions/open.ts': `import { defineAction } from '@bitakit/core';
|
|
@@ -156,28 +156,28 @@ export default defineAction({ title: '${title}', href: '/${name}', groups: ['nav
|
|
|
156
156
|
*/
|
|
157
157
|
export function sampleFiles({ navigationSlot } = {}) {
|
|
158
158
|
return {
|
|
159
|
-
'todos/services/
|
|
159
|
+
'todos/services/list.ts': `import { defineService } from '@bitakit/core';
|
|
160
160
|
|
|
161
161
|
export type Todo = { id: number; title: string };
|
|
162
162
|
|
|
163
163
|
// The todo list. It lives in memory, so a reload starts empty; call your API here later.
|
|
164
164
|
export default defineService(({ store, events }) => {
|
|
165
|
-
const state = store<{
|
|
165
|
+
const state = store<{ todos: Todo[] }>({ todos: [] });
|
|
166
166
|
let next = 1;
|
|
167
167
|
return {
|
|
168
168
|
state,
|
|
169
169
|
add(title: string) {
|
|
170
|
-
const
|
|
171
|
-
state.set((current) => ({
|
|
172
|
-
events.emit('todos.changed', { kind: 'added', title:
|
|
170
|
+
const todo = { id: next++, title: title.trim() };
|
|
171
|
+
state.set((current) => ({ todos: [...current.todos, todo] }));
|
|
172
|
+
events.emit('todos.changed', { kind: 'added', title: todo.title });
|
|
173
173
|
},
|
|
174
174
|
remove(id: number) {
|
|
175
|
-
const
|
|
176
|
-
state.set((current) => ({
|
|
177
|
-
if (
|
|
175
|
+
const removed = state.get().todos.find((todo) => todo.id === id);
|
|
176
|
+
state.set((current) => ({ todos: current.todos.filter((todo) => todo.id !== id) }));
|
|
177
|
+
if (removed) events.emit('todos.changed', { kind: 'removed', title: removed.title });
|
|
178
178
|
},
|
|
179
179
|
clear() {
|
|
180
|
-
state.set({
|
|
180
|
+
state.set({ todos: [] });
|
|
181
181
|
events.emit('todos.changed', { kind: 'cleared' });
|
|
182
182
|
},
|
|
183
183
|
};
|
|
@@ -189,8 +189,8 @@ export default defineAction<string>({
|
|
|
189
189
|
title: 'Add',
|
|
190
190
|
// Bound buttons stay disabled while the input is empty or the list is full.
|
|
191
191
|
enabled: ({ input, services, settings }) =>
|
|
192
|
-
!!input?.trim() && services.todos.
|
|
193
|
-
execute: ({ services, input }) => services.todos.
|
|
192
|
+
!!input?.trim() && services.todos.list.state.get().todos.length < settings.todos.limit.get(),
|
|
193
|
+
execute: ({ services, input }) => services.todos.list.add(input),
|
|
194
194
|
});
|
|
195
195
|
`,
|
|
196
196
|
'todos/actions/remove.ts': `import { defineAction } from '@bitakit/core';
|
|
@@ -199,16 +199,16 @@ export default defineAction<number>({
|
|
|
199
199
|
title: 'Remove',
|
|
200
200
|
// Each row tracks its own pending state.
|
|
201
201
|
concurrency: 'per-input',
|
|
202
|
-
execute: ({ services, input }) => services.todos.
|
|
202
|
+
execute: ({ services, input }) => services.todos.list.remove(input),
|
|
203
203
|
});
|
|
204
204
|
`,
|
|
205
205
|
'todos/actions/clear.ts': `import { defineAction } from '@bitakit/core';
|
|
206
206
|
|
|
207
207
|
export default defineAction({
|
|
208
208
|
title: 'Clear all',
|
|
209
|
-
enabled: ({ services }) => services.todos.
|
|
209
|
+
enabled: ({ services }) => services.todos.list.state.get().todos.length > 0,
|
|
210
210
|
confirm: 'Delete every todo?',
|
|
211
|
-
execute: ({ services }) => services.todos.
|
|
211
|
+
execute: ({ services }) => services.todos.list.clear(),
|
|
212
212
|
success: 'All todos deleted',
|
|
213
213
|
});
|
|
214
214
|
`,
|
|
@@ -243,7 +243,7 @@ import { Button, Input, PageHeader } from '@bitakit/ui/components';
|
|
|
243
243
|
|
|
244
244
|
// Served at /todos. Each button takes its label, disabled and pending state from its Action.
|
|
245
245
|
export default function TodosPage() {
|
|
246
|
-
const
|
|
246
|
+
const todos = useServiceState('todos.list', (state) => state.todos, []);
|
|
247
247
|
const [title, setTitle] = useState('');
|
|
248
248
|
return (
|
|
249
249
|
<div className="flex flex-col gap-6">
|
|
@@ -261,10 +261,10 @@ export default function TodosPage() {
|
|
|
261
261
|
</Action>
|
|
262
262
|
</form>
|
|
263
263
|
<ul className="flex flex-col gap-2">
|
|
264
|
-
{
|
|
265
|
-
<li key={
|
|
266
|
-
<span className="min-w-0 truncate">{
|
|
267
|
-
<Action id="todos.remove" input={
|
|
264
|
+
{todos.map((todo) => (
|
|
265
|
+
<li key={todo.id} className="flex items-center justify-between gap-2">
|
|
266
|
+
<span className="min-w-0 truncate">{todo.title}</span>
|
|
267
|
+
<Action id="todos.remove" input={todo.id}>
|
|
268
268
|
<Button variant="ghost" size="sm" />
|
|
269
269
|
</Action>
|
|
270
270
|
</li>
|
|
@@ -332,16 +332,16 @@ import { Button, Input, PageHeader } from '@bitakit/ui/components';
|
|
|
332
332
|
// Served at ${path}; the path comes from this file's location under ui/pages.
|
|
333
333
|
export default function ${component}() {
|
|
334
334
|
// Re-renders whenever the service's store changes.
|
|
335
|
-
const
|
|
335
|
+
const entries = useServiceState('${plugin}.list', (state) => state.entries, []);
|
|
336
336
|
const [title, setTitle] = useState('');
|
|
337
337
|
return (
|
|
338
338
|
<div className="flex flex-col gap-6">
|
|
339
|
-
<PageHeader title="${title}" subtitle="Add and remove
|
|
339
|
+
<PageHeader title="${title}" subtitle="Add and remove entries. Everything here lives in the ${plugin} plugin." />
|
|
340
340
|
<div className="flex gap-2">
|
|
341
341
|
<Input
|
|
342
342
|
value={title}
|
|
343
|
-
placeholder="New
|
|
344
|
-
aria-label="New
|
|
343
|
+
placeholder="New entry"
|
|
344
|
+
aria-label="New entry"
|
|
345
345
|
onChange={(event) => setTitle(event.target.value)}
|
|
346
346
|
/>
|
|
347
347
|
<Action id="${plugin}.add" input={title} onExecuted={() => setTitle('')}>
|
|
@@ -349,10 +349,10 @@ export default function ${component}() {
|
|
|
349
349
|
</Action>
|
|
350
350
|
</div>
|
|
351
351
|
<ul className="flex flex-col gap-2">
|
|
352
|
-
{
|
|
353
|
-
<li key={
|
|
354
|
-
<span className="min-w-0 truncate">{
|
|
355
|
-
<Action id="${plugin}.remove" input={
|
|
352
|
+
{entries.map((entry) => (
|
|
353
|
+
<li key={entry.id} className="flex items-center justify-between gap-2">
|
|
354
|
+
<span className="min-w-0 truncate">{entry.title}</span>
|
|
355
|
+
<Action id="${plugin}.remove" input={entry.id}>
|
|
356
356
|
<Button variant="ghost" size="sm" />
|
|
357
357
|
</Action>
|
|
358
358
|
</li>
|
|
@@ -367,16 +367,18 @@ export default function ${component}() {
|
|
|
367
367
|
`;
|
|
368
368
|
}
|
|
369
369
|
|
|
370
|
-
|
|
370
|
+
/** `plugin` names the owning plugin in the hint when the caller knows it. */
|
|
371
|
+
export function actionFile(name, plugin) {
|
|
371
372
|
const segments = name.split('/');
|
|
372
373
|
segments.forEach((segment) => validateName(segment, 'action name'));
|
|
374
|
+
const services = plugin ? `services${member(plugin)}` : 'services.<plugin>';
|
|
373
375
|
return `import { defineAction } from '@bitakit/core';
|
|
374
376
|
|
|
375
377
|
export default defineAction({
|
|
376
378
|
title: '${titleOf(segments.at(-1))}',
|
|
377
379
|
// Services are services.<plugin>.<name>; reading an unknown one fails with a named error.
|
|
378
380
|
execute: ({ services }) => {
|
|
379
|
-
// Call your services here, for example services
|
|
381
|
+
// Call your services here, for example ${services}.<name>.<method>().
|
|
380
382
|
},
|
|
381
383
|
});
|
|
382
384
|
`;
|
|
@@ -519,6 +521,45 @@ export default defineInterceptor({
|
|
|
519
521
|
`;
|
|
520
522
|
}
|
|
521
523
|
|
|
524
|
+
/**
|
|
525
|
+
* A headless test of one app plugin (`bitakit add test`), run from the app root with `node --test`.
|
|
526
|
+
* `directory` is the plugin folder relative to that root; `id` is only needed when the folder is
|
|
527
|
+
* not under a `plugins` directory. `shellSlots` are the Shell slots its Actions are placed in:
|
|
528
|
+
* without Shell in the test, a stand-in has to own them or startup fails.
|
|
529
|
+
*/
|
|
530
|
+
export function testFile(plugin, { directory, id, shellSlots = [] }) {
|
|
531
|
+
const options = [
|
|
532
|
+
...(id ? [`id: '${id}'`] : []),
|
|
533
|
+
...(shellSlots.length ? ['plugins: [shell]'] : []),
|
|
534
|
+
];
|
|
535
|
+
const slots = shellSlots.map(
|
|
536
|
+
(slot) =>
|
|
537
|
+
`${/^[A-Za-z_$][\w$]*$/.test(slot) ? slot : `'${slot}'`}: defineSlot({ accepts: 'actions' })`,
|
|
538
|
+
);
|
|
539
|
+
const shell = shellSlots.length
|
|
540
|
+
? `
|
|
541
|
+
// ${plugin} places Actions in Shell slots; this stand-in owns them so the plugin starts without Shell.
|
|
542
|
+
const shell = definePlugin({
|
|
543
|
+
id: 'shell',
|
|
544
|
+
slots: ${slots.length === 1 ? `{ ${slots[0]} }` : `{\n ${slots.join(',\n ')},\n }`},
|
|
545
|
+
});
|
|
546
|
+
`
|
|
547
|
+
: '';
|
|
548
|
+
return `import assert from 'node:assert/strict';
|
|
549
|
+
import test from 'node:test';
|
|
550
|
+
${shellSlots.length ? "import { definePlugin, defineSlot } from '@bitakit/core';\n" : ''}import { mountPlugin } from '@bitakit/core/testing';
|
|
551
|
+
${shell}
|
|
552
|
+
test('the ${plugin} plugin starts headlessly', async () => {
|
|
553
|
+
const plugin = await mountPlugin('${directory}'${options.length ? `, { ${options.join(', ')} }` : ''});
|
|
554
|
+
try {
|
|
555
|
+
assert.equal(plugin.runtime.isReady(plugin.id), true);
|
|
556
|
+
} finally {
|
|
557
|
+
await plugin.stop();
|
|
558
|
+
}
|
|
559
|
+
});
|
|
560
|
+
`;
|
|
561
|
+
}
|
|
562
|
+
|
|
522
563
|
export function configFile(name) {
|
|
523
564
|
return `import { defineConfig } from '@bitakit/core';
|
|
524
565
|
|