@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/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 { agentRules, agentRulesBegin, claudeFileFor } from './agent-rules.mjs';
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
- * Returns `written` (absolute paths; `created` is false for an edited file), `skipped` with the
126
- * reason for each, and the BitaKit packages the app still has to install.
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 agents = await read(at('AGENTS.md'));
232
- if (agents?.includes(agentRulesBegin)) skip(at('AGENTS.md'), 'already has the BitaKit rules');
233
- else {
234
- // The framework's own route folder: src/app or app for Next.js, src/routes for TanStack Start.
235
- const routes =
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
- at('AGENTS.md'),
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
- return { project, written, skipped, install };
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}/items
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 items = `services${member(name)}.items`;
72
+ const list = `services${member(name)}.list`;
73
73
  const files = {
74
- 'services/items.ts': `import { defineService } from '@bitakit/core';
74
+ 'services/list.ts': `import { defineService } from '@bitakit/core';
75
75
 
76
- export type Item = { id: number; title: string };
76
+ export type Entry = { id: number; title: string };
77
77
 
78
78
  /**
79
- * The ${title} plugin's data and behavior. Items live in memory, so a page reload starts
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<{ items: Item[] }>({ items: [] });
85
+ const state = store<{ entries: Entry[] }>({ entries: [] });
86
86
  return {
87
87
  state,
88
88
  add(title: string) {
89
- state.set((s) => ({ items: [...s.items, { id: Date.now(), title: title.trim() }] }));
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) => ({ items: s.items.filter((item) => item.id !== id) }));
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 item',
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 }) => ${items}.add(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 }) => ${items}.remove(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 items store changes.
134
- enabled: ({ services }) => ${items}.state.get().items.length > 0,
135
- confirm: 'Remove all items?',
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 item of ${items}.state.get().items) ${items}.remove(item.id);
137
+ for (const entry of ${list}.state.get().entries) ${list}.remove(entry.id);
138
138
  },
139
- success: 'All items removed',
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/items.ts': `import { defineService } from '@bitakit/core';
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<{ items: Todo[] }>({ items: [] });
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 item = { id: next++, title: title.trim() };
171
- state.set((current) => ({ items: [...current.items, item] }));
172
- events.emit('todos.changed', { kind: 'added', title: item.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 item = state.get().items.find((entry) => entry.id === id);
176
- state.set((current) => ({ items: current.items.filter((entry) => entry.id !== id) }));
177
- if (item) events.emit('todos.changed', { kind: 'removed', title: item.title });
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({ items: [] });
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.items.state.get().items.length < settings.todos.limit.get(),
193
- execute: ({ services, input }) => services.todos.items.add(input),
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.items.remove(input),
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.items.state.get().items.length > 0,
209
+ enabled: ({ services }) => services.todos.list.state.get().todos.length > 0,
210
210
  confirm: 'Delete every todo?',
211
- execute: ({ services }) => services.todos.items.clear(),
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 items = useServiceState('todos.items', (state) => state.items, []);
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
- {items.map((item) => (
265
- <li key={item.id} className="flex items-center justify-between gap-2">
266
- <span className="min-w-0 truncate">{item.title}</span>
267
- <Action id="todos.remove" input={item.id}>
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 items = useServiceState('${plugin}.items', (state) => state.items, []);
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 items. Everything here lives in the ${plugin} plugin." />
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 item"
344
- aria-label="New item"
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
- {items.map((item) => (
353
- <li key={item.id} className="flex items-center justify-between gap-2">
354
- <span className="min-w-0 truncate">{item.title}</span>
355
- <Action id="${plugin}.remove" input={item.id}>
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
- export function actionFile(name) {
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.notes.items.add('…').
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