@bitakit/cli 0.2.3 → 0.2.5

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 CHANGED
@@ -38,10 +38,41 @@ in new apps; `npx @bitakit/create-app .` creates the app in a folder that holds
38
38
  agent files, so the skill lands where an open agent session works. See the [skill README](skills/bitakit-app-development/README.md) for how to use it
39
39
  and requests to try.
40
40
 
41
+ ## Update BitaKit
42
+
43
+ Keep every `@bitakit/*` package on one release line (0.2.x, then 0.3.x). Only packages whose
44
+ shipped content changed get a patch release, so patch versions may differ within a line; `doctor`
45
+ accepts that and reports packages on different lines as an error.
46
+
47
+ Within a line, `npm update` installs the newest patches the caret ranges allow. Name the
48
+ `@bitakit/*` packages your `package.json` lists (plain `npm update` updates every dependency):
49
+
50
+ ```sh
51
+ npm update @bitakit/core @bitakit/ui @bitakit/next @bitakit/cli @bitakit/discovery
52
+ ```
53
+
54
+ `package.json` keeps its ranges; `package-lock.json` records the new versions.
55
+
56
+ A new line is outside those ranges. Install all `@bitakit/*` packages at it in one command, here
57
+ 0.3; each keeps its place in `dependencies` or `devDependencies`:
58
+
59
+ ```sh
60
+ npm install @bitakit/core@0.3 @bitakit/ui@0.3 @bitakit/next@0.3 @bitakit/cli@0.3 @bitakit/discovery@0.3
61
+ ```
62
+
63
+ Do not move one package alone (for example `npm install --save-dev @bitakit/cli@latest`): once a
64
+ new line is out, that splits the app across two lines. Follow the new line's upgrade guide when
65
+ it has one, then refresh the agent files and check the project:
66
+
67
+ ```sh
68
+ npx bitakit init --update-agent-files
69
+ npx bitakit doctor
70
+ ```
71
+
41
72
  ### Keep agent files current
42
73
 
43
74
  The installed `SKILL.md` records the CLI version and a checksum of the files as shipped in its
44
- frontmatter `metadata`. After upgrading the BitaKit packages, run:
75
+ frontmatter `metadata`. After updating the BitaKit packages, run:
45
76
 
46
77
  ```sh
47
78
  npx bitakit init --update-agent-files
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bitakit/cli",
3
- "version": "0.2.3",
3
+ "version": "0.2.5",
4
4
  "description": "BitaKit project commands: add plugins and contributions, check a project with doctor.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -71,7 +71,9 @@ Do this once per session, before the first change:
71
71
  agent files out of sync, such as an outdated skill, tell the user and suggest
72
72
  `npx bitakit init --update-agent-files`.
73
73
  4. Read the owning plugin's files before changing them. Generated `src/bitakit.gen.*` files are
74
- evidence for types; never edit them.
74
+ evidence for types; never edit them. For installed plugins, inspect their public contracts/types
75
+ and package README/local documentation before extending them. Keep plugin-specific recipes
76
+ with their owning package.
75
77
  5. Before placing UI, inspect the app's selected composition: which layout frames the page (Shell
76
78
  `sidebar`, the default, or `navbar`; a page's `export const layout`; or `src/layouts/<name>.tsx`)
77
79
  and which component actually renders the slot you want. A declared slot shows nothing until an
@@ -94,7 +96,13 @@ Do this once per session, before the first change:
94
96
  - State lives in services, preferences in settings, operations in Actions bound to controls with
95
97
  `<Action>`. Pages and components live under `ui/` and start with `'use client'` in Next.js.
96
98
  - Use `@bitakit/ui/components` and the app's theme tokens. Keep styling to the existing
97
- components and layout utilities.
99
+ components and layout utilities. Important public UI parts should keep a few stable,
100
+ namespaced classes for intentional external CSS overrides. Reuse existing classes,
101
+ state/ARIA attributes and native hover/focus selectors; no wrapper-by-wrapper class inventory,
102
+ redundant state classes or extra styling system. Use ordinary CSS directly; no Tailwind
103
+ indirection is necessary. The central theme remains the default.
104
+ Document actual class names/states with the owning component, including a direct entry point
105
+ for portaled content.
98
106
  - Build on BitaKit's mechanisms: no own registries, event buses, settings stores or button
99
107
  state, and no edits to generated files or the framework's provider wiring.
100
108
  - Ask before adding a dependency. Install BitaKit packages at the version the app already uses,
@@ -72,7 +72,9 @@ function TodosToolbar() {
72
72
  empty while the slot is pending.
73
73
  - For a slot with a payload, pass it at every outlet:
74
74
  `useSlot('todos.row.menu', { payload: { todoId: todo.id } })` or
75
- `<PluginSlot name="sidebar.footer" payload={{ collapsed }} />`.
75
+ `<PluginSlot name="sidebar.footer" payload={{ collapsed }} />`. Memoize payload objects
76
+ (`useMemo`): a contribution renders again only when its payload changes, not with every render
77
+ of the page around it.
76
78
 
77
79
  ## Contribute a component
78
80
 
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', moduleId: id, properties: ['accepts', 'policy'],
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(path.join(dist, 'plugin.slots.json'), JSON.stringify({
75
- version: 1,
76
- definitions: slotInfo.definitions.map((item) => ({ ...item, file: source(item.file), plugin: id, policy: item.policy ?? 'list' })),
77
- unresolved: slotInfo.unresolved.map(source),
78
- }, null, 2) + '\n');
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) => (value === undefined ? [] : Array.isArray(value) ? value : [value])
93
- .map((entry) => `${manifest.name}/${entry.replace(/^\.\//, '')}`);
94
- await validatePackageStyles([{
95
- name: manifest.name,
96
- manifestFile: path.join(root, 'package.json'),
97
- manifest,
98
- styles: styles(metadata.styles),
99
- theme: styles(metadata.theme),
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 ['name', 'version', 'description', 'author', 'homepage', 'bugs', 'license', 'coverImage', 'tags'])
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 ? `pluginSettingsPage(${load(module.settingsPage, true)})` : undefined;
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) => `pluginSlot(${load(item.file, true)}, ${quote(item.path)}, ${quote(path.relative(module.directory, item.file).split(path.sep).join('/'))})`,
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/doctor.mjs CHANGED
@@ -259,10 +259,10 @@ async function checkWiring(project) {
259
259
  fix: 'Run "npx bitakit migrate", or rename withFoundation to withBitaKit.',
260
260
  }
261
261
  : {
262
- status: 'error',
263
- title: 'next.config does not run BitaKit discovery',
264
- fix: "import { withBitaKit } from '@bitakit/next/config';\nexport default withBitaKit({});",
265
- },
262
+ status: 'error',
263
+ title: 'next.config does not run BitaKit discovery',
264
+ fix: "import { withBitaKit } from '@bitakit/next/config';\nexport default withBitaKit({});",
265
+ },
266
266
  );
267
267
  const scripts = JSON.stringify(project.manifest.scripts ?? {});
268
268
  if (scripts.includes('--webpack'))
@@ -290,10 +290,10 @@ async function checkWiring(project) {
290
290
  fix: 'Run "npx bitakit migrate", or import { bitakit } from \'@bitakit/tanstack/config\' and call bitakit().',
291
291
  }
292
292
  : {
293
- status: 'error',
294
- title: 'vite.config does not run BitaKit discovery',
295
- fix: "import { bitakit } from '@bitakit/tanstack/config';\nplugins: [bitakit(), tanstackStart(), ...]",
296
- },
293
+ status: 'error',
294
+ title: 'vite.config does not run BitaKit discovery',
295
+ fix: "import { bitakit } from '@bitakit/tanstack/config';\nplugins: [bitakit(), tanstackStart(), ...]",
296
+ },
297
297
  );
298
298
  }
299
299
  let provider = false;
@@ -357,7 +357,8 @@ async function mountsProvider(file, root, seen = new Set()) {
357
357
  // The generated file exports BitaKitProvider; the packages export BitaKitRuntimeProvider.
358
358
  if (
359
359
  (entry.name === 'BitaKitProvider' && /bitakit\.gen$/.test(entry.from)) ||
360
- (entry.name === 'BitaKitRuntimeProvider' && /^@bitakit\/(?:ui|next|tanstack)$/.test(entry.from))
360
+ (entry.name === 'BitaKitRuntimeProvider' &&
361
+ /^@bitakit\/(?:ui|next|tanstack)$/.test(entry.from))
361
362
  )
362
363
  return true;
363
364
  const base = entry.from.startsWith('@/')
@@ -460,12 +461,12 @@ async function providedKeys(root, entries) {
460
461
  node.expression.name.text === 'of'
461
462
  ? nameOf(node.expression.expression)
462
463
  : ts.isCallExpression(node) &&
463
- ts.isIdentifier(node.expression) &&
464
- ['serviceKey', 'defineContract'].includes(node.expression.text) &&
465
- node.arguments[0] &&
466
- ts.isStringLiteralLike(node.arguments[0])
467
- ? node.arguments[0].text
468
- : undefined;
464
+ ts.isIdentifier(node.expression) &&
465
+ ['serviceKey', 'defineContract'].includes(node.expression.text) &&
466
+ node.arguments[0] &&
467
+ ts.isStringLiteralLike(node.arguments[0])
468
+ ? node.arguments[0].text
469
+ : undefined;
469
470
  const visit = (node) => {
470
471
  if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
471
472
  const name = nameOf(node.initializer);
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, ['bitakit.config.ts', 'foundation.config.ts']);
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 =