@bitakit/cli 0.2.2 → 0.2.4
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
|
|
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
|
@@ -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
|
|
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();
|