@bitakit/cli 0.2.2 → 0.2.3

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bitakit/cli",
3
- "version": "0.2.2",
3
+ "version": "0.2.3",
4
4
  "description": "BitaKit project commands: add plugins and contributions, check a project with doctor.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -60,8 +60,8 @@ npx @bitakit/create-app@latest <directory> --framework next --features <list|non
60
60
  Do this once per session, before the first change:
61
61
 
62
62
  1. Read `package.json`: the framework (`next` or `@tanstack/react-start`), the scripts and the
63
- installed `@bitakit/*` versions. All BitaKit packages should share one version; if they do not,
64
- say so and follow what is installed. Note the optional features: `@bitakit/shell` (the
63
+ installed `@bitakit/*` versions. All BitaKit packages should be on one release line (0.2.x;
64
+ patch versions may differ); if they are not, say so and follow what is installed. Note the optional features: `@bitakit/shell` (the
65
65
  sidebar/navbar frame), `@bitakit/app-preferences` (Settings pages), `@bitakit/quick-search`.
66
66
  2. Run `npx bitakit info --json` for the IDs the app's own plugins declare (Actions, services,
67
67
  pages, events, settings, slots). Run `npx bitakit slots` for every slot you can fill, including
@@ -84,6 +84,9 @@ Do this once per session, before the first change:
84
84
  `config`, `slot`, `slot-definition`, `dialog`, `provider`). `events`, `settings` and
85
85
  `settings-page` take only `<plugin>`; `layout <name>` is app-level; `test <plugin>` writes
86
86
  `tests/<plugin>.test.ts`. Existing files are never overwritten.
87
+ - Folders are the default layout; flat files (`actions.add.ts`, or one `actions.ts` for several
88
+ Actions) declare the same IDs and are equally fine. Follow the layout the app already uses; see
89
+ [references/plugins-and-pages.md](references/plugins-and-pages.md#folders-or-flat-files).
87
90
  - Replace the generated template bodies and tutorial comments with the real implementation.
88
91
  - Extend a feature you do not own from your own plugin: listen to its events, fill its slots,
89
92
  call its services (declared with `requires`) and read its settings. Change the owner only when
@@ -42,6 +42,29 @@ file paths, so there is nothing to register.
42
42
  a file). Put shared components in `ui/components/`, which discovery treats as ordinary imports.
43
43
  - Renaming a file changes its ID or URL. Update the `href`s and `<Action id>`s that use it.
44
44
 
45
+ ## Folders or flat files
46
+
47
+ Folders are the default, and `bitakit add` writes them. A flat layout is just as valid, because a
48
+ dot means the same as a folder. These all declare the Action `todos.add`:
49
+
50
+ | Layout | File in `src/plugins/todos/` |
51
+ | -------------------- | ---------------------------------------- |
52
+ | Folder (default) | `actions/add.ts` |
53
+ | Flat file | `actions.add.ts` |
54
+ | One file for several | `actions.ts` exporting `{ add, remove }` |
55
+
56
+ - The same works for `services`, `configs`, `slots` and `interceptors`, and for pages inside
57
+ `ui/pages/`. React files always stay under `ui/`.
58
+ - `events.ts`, `settings.ts`, `setup.ts` and `plugin.config.ts` are one file per plugin in
59
+ either layout. Every file and folder is optional: add only what the feature needs.
60
+ - Follow the layout the app already uses. When the user prefers flat files, write them by hand
61
+ with the same content `bitakit add` would generate. Both layouts may be mixed; one ID needs
62
+ exactly one file, so two spellings of the same ID fail as a duplicate.
63
+ - Folders keep a growing feature tidy and each change in its own file; flat files keep a small
64
+ plugin visible at a glance. Moving between them never changes an ID.
65
+ - Do not run `bitakit migrate` on a flat app: it is the 0.1 upgrade and moves dotted files into
66
+ folders.
67
+
45
68
  ## Add a page
46
69
 
47
70
  ```sh
package/src/doctor.mjs CHANGED
@@ -163,6 +163,13 @@ async function checkVersions(project) {
163
163
  const versions = [...new Set(packages.map((item) => item.version))];
164
164
  if (versions.length === 1)
165
165
  return { status: 'ok', title: `All ${packages.length} @bitakit packages are ${versions[0]}` };
166
+ // Only changed packages get a patch release, so patch versions may differ within one line.
167
+ const lines = [...new Set(packages.map((item) => releaseLine(item.version)))];
168
+ if (lines.length === 1)
169
+ return {
170
+ status: 'ok',
171
+ title: `All ${packages.length} @bitakit packages are on the ${lines[0]}.x release line`,
172
+ };
166
173
  return {
167
174
  status: 'error',
168
175
  title: 'Mixed @bitakit versions',
@@ -170,6 +177,11 @@ async function checkVersions(project) {
170
177
  fix: `Install one release for all of them: npm install ${packages.map((item) => `${item.name}@latest`).join(' ')}`,
171
178
  };
172
179
  }
180
+ /** The versions a caret range accepts together: `0.2` for 0.2.x, `1` for 1.x. */
181
+ function releaseLine(version) {
182
+ const [major, minor] = version.split('.');
183
+ return major === '0' ? `0.${minor}` : major;
184
+ }
173
185
  /** Linked plugins with their own node_modules load a second copy of Core. */
174
186
  async function checkCopies(project) {
175
187
  const copies = new Set();