@bitakit/cli 0.2.5 → 0.2.7
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/AGENTS.md +37 -0
- package/CLAUDE.md +1 -0
- package/README.md +14 -2
- package/package.json +5 -3
- package/skills/bitakit-app-development/README.md +27 -14
- package/skills/bitakit-app-development/SKILL.md +100 -69
- package/skills/bitakit-app-development/references/actions.md +2 -1
- package/skills/bitakit-app-development/references/best-practices.md +214 -0
- package/skills/bitakit-app-development/references/create-app.md +57 -0
- package/skills/bitakit-app-development/references/data-and-api.md +321 -0
- package/skills/bitakit-app-development/references/layouts-and-screens.md +219 -0
- package/skills/bitakit-app-development/references/plugin-guides.md +63 -0
- package/skills/bitakit-app-development/references/plugins-and-pages.md +11 -12
- package/skills/bitakit-app-development/references/slots.md +26 -17
- package/skills/bitakit-app-development/references/testing-and-preview.md +12 -9
- package/skills/bitakit-app-development/references/worked-example.md +312 -0
- package/src/add.mjs +45 -12
- package/src/agent-rules.mjs +45 -3
- package/src/cli.mjs +14 -8
- package/src/doctor.mjs +34 -0
- package/src/slots.mjs +55 -1
- package/src/templates.mjs +9 -6
package/AGENTS.md
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# @bitakit/cli — guide for agents
|
|
2
|
+
|
|
3
|
+
> For agents building an app with this package (it ships in `node_modules/@bitakit/cli`). To
|
|
4
|
+
> change the package itself, follow the repository's own AGENTS.md instead.
|
|
5
|
+
|
|
6
|
+
The `bitakit` command. It scaffolds plugins and contributions, regenerates the wiring and
|
|
7
|
+
checks a project. It also ships the `bitakit-app-development` skill, which `create-app` and
|
|
8
|
+
`bitakit init` install into `.agents/skills/` and `.claude/skills/`: read that skill first.
|
|
9
|
+
|
|
10
|
+
## Commands agents use
|
|
11
|
+
|
|
12
|
+
| Command | Does |
|
|
13
|
+
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
|
|
14
|
+
| `npx bitakit add plugin <name>` | A plugin with a page and a navigation link (`--example`, `--minimal`) |
|
|
15
|
+
| `npx bitakit add <kind> <plugin>/<name>` | `action`, `service`, `page`, `interceptor`, `config`, `slot`, `slot-definition`, `dialog`, `provider` |
|
|
16
|
+
| `npx bitakit add events\|settings\|settings-page <plugin>` | The plugin's single file of that kind |
|
|
17
|
+
| `npx bitakit add layout <family>[/<variant>]` | A candidate for `layout.<family>` (`--plugin <id>` for a plugin) |
|
|
18
|
+
| `npx bitakit add test <plugin>` | A headless test, plus the setup commands it still needs |
|
|
19
|
+
| `npx bitakit info --json` | Plugins, services, Actions, events, settings, pages |
|
|
20
|
+
| `npx bitakit slots [--json]` | Every slot, its owner, contributions and, for replaceable parts, what renders |
|
|
21
|
+
| `npx bitakit doctor [--json]` | Wiring, versions, routes, links, slots, replaceable parts, agent files |
|
|
22
|
+
| `npx bitakit check-page /<path> --json` | Opens the page headlessly and reports headings and errors (Playwright) |
|
|
23
|
+
| `npx bitakit init --update-agent-files` | Refreshes AGENTS.md's BitaKit block and unedited skill copies |
|
|
24
|
+
|
|
25
|
+
`add` never overwrites a file. Run `npm run typecheck` and `npx bitakit doctor` after changes;
|
|
26
|
+
doctor exits 1 on errors and names the fix.
|
|
27
|
+
|
|
28
|
+
`add plugin` (including `--example` and `--minimal`) writes an `AGENTS.md` inside that plugin
|
|
29
|
+
and a `CLAUDE.md` importing it. Read the local guide before editing the plugin. Keep its purpose,
|
|
30
|
+
contracts and checks there and update them with the code; shared rules stay in the app guide.
|
|
31
|
+
|
|
32
|
+
## Rules
|
|
33
|
+
|
|
34
|
+
- Replace template bodies and tutorial comments with the real implementation.
|
|
35
|
+
- `bitakit migrate` is the 0.1 upgrade; do not run it to tidy a current project.
|
|
36
|
+
- Install printed Playwright or test dependencies only within the user's authorized scope;
|
|
37
|
+
obtain missing approval without requesting an authorization already given again.
|
package/CLAUDE.md
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
@AGENTS.md
|
package/README.md
CHANGED
|
@@ -96,6 +96,10 @@ Action; discovery connects it, so there is nothing to register. `--example` writ
|
|
|
96
96
|
feature (the service `notes.list`, events, Actions, page); `--minimal` only that service, its
|
|
97
97
|
events and one action.
|
|
98
98
|
|
|
99
|
+
All three modes also write the plugin's own `AGENTS.md` with its starter purpose, actual files,
|
|
100
|
+
public IDs and checks, plus a `CLAUDE.md` containing `@AGENTS.md`. Keep that local guide current
|
|
101
|
+
as the feature develops; it is not replaced by `init --update-agent-files`.
|
|
102
|
+
|
|
99
103
|
Add single files to an existing plugin (inside a plugin package, give only the name):
|
|
100
104
|
|
|
101
105
|
```sh
|
|
@@ -105,6 +109,8 @@ npx bitakit add page notes/archive # ui/pages/archive.tsx → /not
|
|
|
105
109
|
npx bitakit add interceptor notes/audit # interceptors/audit.ts
|
|
106
110
|
npx bitakit add config notes/limits # configs/limits.ts → app.config.notes.limits
|
|
107
111
|
npx bitakit add events notes # events.ts
|
|
112
|
+
npx bitakit add layout auth/split # src/layouts/auth/split.tsx → a candidate for layout.auth
|
|
113
|
+
npx bitakit add layout auth --plugin brand # src/plugins/brand/ui/layouts/auth.tsx
|
|
108
114
|
```
|
|
109
115
|
|
|
110
116
|
The file path decides the ID; nested names such as `notes/team/invite` create
|
|
@@ -146,11 +152,17 @@ npx bitakit info [--json] # the plugins, services, actions, events and pages d
|
|
|
146
152
|
npx bitakit slots [--json] # every slot you can fill: owner, accepts and this app's contributions
|
|
147
153
|
```
|
|
148
154
|
|
|
155
|
+
For a replaceable (`single`) slot, `slots` also prints which candidate renders, from the app's
|
|
156
|
+
files and `choose` in `bitakit.config.ts` (`renders app:split`, or `renders the default: choose
|
|
157
|
+
one of ...`); `--json` adds `selection: { candidates, renders, reason, choice }`. Layout files
|
|
158
|
+
count as candidates of `layout.<family>`. Packages can add candidates at runtime.
|
|
159
|
+
|
|
149
160
|
Doctor checks package versions, duplicate copies of `@bitakit/core`, the config wrapper and
|
|
150
161
|
provider wiring, scripts that still force Webpack or `foundation-generate`, ignored generated
|
|
151
162
|
files, plugin pages and links no route reaches, colliding service names, `requires` entries that
|
|
152
|
-
name nothing, plugin dependency cycles, missing package styles, deprecated layouts
|
|
153
|
-
|
|
163
|
+
name nothing, plugin dependency cycles, missing package styles, deprecated layouts, replaceable
|
|
164
|
+
parts without a decision (several candidates in the app's files, or `choose` entries for unknown
|
|
165
|
+
or non-single slots) and agent files that are out of sync, and prints a fix for each problem.
|
|
154
166
|
|
|
155
167
|
The `requires` check reads the string literals of `requires` in services, actions, interceptors
|
|
156
168
|
and in `export const requires` of provider files. A name must be a service ID, an `exposeAs`
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bitakit/cli",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.7",
|
|
4
4
|
"description": "BitaKit project commands: add plugins and contributions, check a project with doctor.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -14,6 +14,8 @@
|
|
|
14
14
|
"src",
|
|
15
15
|
"skills",
|
|
16
16
|
"README.md",
|
|
17
|
+
"AGENTS.md",
|
|
18
|
+
"CLAUDE.md",
|
|
17
19
|
"LICENSE"
|
|
18
20
|
],
|
|
19
21
|
"engines": {
|
|
@@ -23,8 +25,8 @@
|
|
|
23
25
|
"test": "node --test tests/*.test.mjs"
|
|
24
26
|
},
|
|
25
27
|
"dependencies": {
|
|
26
|
-
"@bitakit/core": "^0.2.
|
|
27
|
-
"@bitakit/discovery": "^0.2.
|
|
28
|
+
"@bitakit/core": "^0.2.6",
|
|
29
|
+
"@bitakit/discovery": "^0.2.4",
|
|
28
30
|
"commander": "15.0.0",
|
|
29
31
|
"typescript": "^5.9.3"
|
|
30
32
|
},
|
|
@@ -75,20 +75,33 @@ save a recipe with a title and ingredients" works the same way.
|
|
|
75
75
|
|
|
76
76
|
## What the skill covers
|
|
77
77
|
|
|
78
|
-
| Task
|
|
79
|
-
|
|
|
80
|
-
| Create a
|
|
81
|
-
|
|
|
82
|
-
|
|
|
83
|
-
|
|
|
84
|
-
|
|
|
85
|
-
|
|
|
86
|
-
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
78
|
+
| Task | Recipe |
|
|
79
|
+
| -------------------------------------------------------------------------- | ----------------------------------------------------------- |
|
|
80
|
+
| Create a new app or a standalone plugin package | [create-app.md](references/create-app.md) |
|
|
81
|
+
| Build a whole feature step by step (Bookmarks) | [worked-example.md](references/worked-example.md) |
|
|
82
|
+
| Create a plugin, a page or a sidebar link | [plugins-and-pages.md](references/plugins-and-pages.md) |
|
|
83
|
+
| Add an Action and bind it to a button or link | [actions.md](references/actions.md) |
|
|
84
|
+
| Keep shared state, use another plugin's service, send and receive events | [services-and-events.md](references/services-and-events.md) |
|
|
85
|
+
| Declare a slot, render it, contribute to one | [slots.md](references/slots.md) |
|
|
86
|
+
| Block, check or observe Actions | [interceptors.md](references/interceptors.md) |
|
|
87
|
+
| Add a user setting | [settings.md](references/settings.md) |
|
|
88
|
+
| Replace a layout, the frame, a 404 or error page, or another plugin's part | [layouts-and-screens.md](references/layouts-and-screens.md) |
|
|
89
|
+
| Load and save data through an API route | [data-and-api.md](references/data-and-api.md) |
|
|
90
|
+
| Avoid common mistakes; naming | [best-practices.md](references/best-practices.md) |
|
|
91
|
+
| Change the app's colors, fonts or theme | Theme files in the `@bitakit/shell` README |
|
|
92
|
+
| Test a plugin and check it in the browser | [testing-and-preview.md](references/testing-and-preview.md) |
|
|
93
|
+
| Keep a plugin's description, contracts and checks beside its code | [plugin-guides.md](references/plugin-guides.md) |
|
|
94
|
+
|
|
95
|
+
The agent selects the recipe and checks relevant to the request. For feature work it reads
|
|
96
|
+
the owning plugin's guide and installed package contracts, uses `info`, `slots` and `doctor`
|
|
97
|
+
where needed, then verifies the changed behavior. Documentation-only edits need source and
|
|
98
|
+
link checks; UI changes need interaction checks in the running app. Existing authorization for
|
|
99
|
+
tests or dependencies is retained. The report says what was built, where it appears and what
|
|
100
|
+
was actually verified.
|
|
101
|
+
|
|
102
|
+
Complete examples stay in references and are read on demand. The skill reuses BitaKit's CLI
|
|
103
|
+
for scaffolding, inspection and checks, plus the app's scripts and test runner; it does not
|
|
104
|
+
ship a second implementation of those tools.
|
|
92
105
|
|
|
93
106
|
## Keep the skill current
|
|
94
107
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: bitakit-app-development
|
|
3
|
-
description:
|
|
3
|
+
description: Build, extend, inspect and test applications using @bitakit packages. Use for BitaKit app creation and plugin features, Actions, services, events, settings, slots, pages, themes and layouts. For changes to BitaKit's own package implementation, follow its repository development guide instead.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# BitaKit app development
|
|
@@ -13,86 +13,112 @@ slots.
|
|
|
13
13
|
Your job: build what the user asks inside the plugin that owns it, check it in the running app,
|
|
14
14
|
and explain in plain words what you built and why.
|
|
15
15
|
|
|
16
|
+
## Match the task
|
|
17
|
+
|
|
18
|
+
- For an explanation or review, inspect relevant files and report findings. Do not turn it
|
|
19
|
+
into implementation, dependency upgrades or unrelated repairs.
|
|
20
|
+
- For a change, preserve the user's scope and existing authorization. Ask only for missing
|
|
21
|
+
decisions or permissions needed for the work. Approval already given for dependencies or
|
|
22
|
+
tests does not need to be requested again. Follow the execution environment's approval
|
|
23
|
+
controls when a command needs them.
|
|
24
|
+
- This skill targets consumer apps. Changes to BitaKit packages themselves follow the
|
|
25
|
+
repository's development guide, release rules and tests.
|
|
26
|
+
|
|
16
27
|
## Pick the recipe
|
|
17
28
|
|
|
18
|
-
Read the reference for the task
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
| The user wants | Read
|
|
22
|
-
| ---------------------------------------------------------------------------------- |
|
|
23
|
-
|
|
|
24
|
-
| A
|
|
25
|
-
|
|
|
26
|
-
| A
|
|
27
|
-
|
|
|
28
|
-
| A
|
|
29
|
-
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
- `--features` is a comma-separated subset of `preferences`, `shell` and `quick-search`, or
|
|
43
|
-
`none`. Without it the app gets `shell,quick-search` (a sidebar frame, Settings and search).
|
|
44
|
-
Choose it to match the app the user describes. Add `--sample` for the working Todo sample.
|
|
45
|
-
- `--yes` skips the prompts, which would otherwise wait for input.
|
|
46
|
-
- When the session's folder is empty or holds only `.git` and agent files (`AGENTS.md`,
|
|
47
|
-
`CLAUDE.md`, `.agents/`, `.claude/`, ...), use `.` as `<directory>` so the app's rules and this
|
|
48
|
-
skill land in the session's folder; create-app keeps and merges those files. The running session
|
|
49
|
-
may not list a skill that did not exist at its start: read `AGENTS.md` and
|
|
50
|
-
`.agents/skills/bitakit-app-development/SKILL.md` directly, and suggest restarting the session.
|
|
51
|
-
- Otherwise use a new directory, then tell the user to open the agent in `<directory>`, or read
|
|
52
|
-
`<directory>/AGENTS.md` before continuing.
|
|
53
|
-
- Suggest `git init` (when there is no `.git`) and a first commit so later changes are easy to
|
|
54
|
-
review.
|
|
55
|
-
- Scaffolding and installs need network access. If the sandbox blocks a command, ask for
|
|
56
|
-
approval or ask the user to run it; never hand-write generated files instead.
|
|
29
|
+
Read the reference needed for the task, then follow its links only when needed. Each has
|
|
30
|
+
commands, file locations, examples and the rules that matter; do not load every recipe.
|
|
31
|
+
|
|
32
|
+
| The user wants | Read |
|
|
33
|
+
| ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
|
|
34
|
+
| Create an app or a standalone plugin package | [references/create-app.md](references/create-app.md) |
|
|
35
|
+
| A whole new feature (plan, files, checks, report, step by step) | [references/worked-example.md](references/worked-example.md) |
|
|
36
|
+
| A new feature, a page, or a link in the sidebar | [references/plugins-and-pages.md](references/plugins-and-pages.md) |
|
|
37
|
+
| A button, link, menu entry or operation | [references/actions.md](references/actions.md) |
|
|
38
|
+
| Shared state or logic, or reacting to another feature | [references/services-and-events.md](references/services-and-events.md) |
|
|
39
|
+
| A place other features can extend, or UI in the header, sidebar or another feature | [references/slots.md](references/slots.md) |
|
|
40
|
+
| Another layout or frame, their own 404, error or sign-in page, a replaceable part | [references/layouts-and-screens.md](references/layouts-and-screens.md) |
|
|
41
|
+
| A rule around Actions: block, check or observe them | [references/interceptors.md](references/interceptors.md) |
|
|
42
|
+
| A user preference | [references/settings.md](references/settings.md) |
|
|
43
|
+
| Data that survives a reload or comes from a server or database | [references/data-and-api.md](references/data-and-api.md) |
|
|
44
|
+
| The app's colors, fonts or a theme file | The Theme files section of `node_modules/@bitakit/shell/README.md` |
|
|
45
|
+
| Tests, the browser preview, or what to report | [references/testing-and-preview.md](references/testing-and-preview.md) |
|
|
46
|
+
| Write or update a plugin's own guide | [references/plugin-guides.md](references/plugin-guides.md) |
|
|
47
|
+
| Diagnose a common mistake or review a pattern | Relevant section of [references/best-practices.md](references/best-practices.md) |
|
|
48
|
+
|
|
49
|
+
The recipes extend the Todo sample (`create-app --sample`): `todos` owns the list and `activity`
|
|
50
|
+
extends it. The worked example and the data recipe build a Bookmarks feature from scratch. Use
|
|
51
|
+
the user's own domain names in real code. Keep complete examples available in references
|
|
52
|
+
without loading them for unrelated tasks.
|
|
57
53
|
|
|
58
54
|
## Inspect the app
|
|
59
55
|
|
|
60
|
-
|
|
56
|
+
Inspect what the task needs; reuse findings while the app's configuration remains unchanged:
|
|
61
57
|
|
|
62
58
|
1. Read `package.json`: the framework (`next` or `@tanstack/react-start`), the scripts and the
|
|
63
59
|
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.
|
|
60
|
+
patch versions may differ); if they are not, say so and follow what is installed. Preserve
|
|
61
|
+
the app's framework and package manager. Note the optional features: `@bitakit/shell` (the
|
|
65
62
|
sidebar/navbar frame), `@bitakit/app-preferences` (Settings pages), `@bitakit/quick-search`.
|
|
66
|
-
2.
|
|
67
|
-
|
|
63
|
+
2. When IDs matter, run `npx bitakit info --json` for the app's plugins. For UI placement or
|
|
64
|
+
extension work, run `npx bitakit slots` for the slots you can fill, including
|
|
68
65
|
those of installed packages such as Shell: its owner, what it accepts and what the app already
|
|
69
66
|
puts there (`--json` adds contributors and the payload keys of the app's own slots).
|
|
70
|
-
3.
|
|
67
|
+
3. For wiring or runtime work, run `npx bitakit doctor` to establish the current state. Fix what
|
|
68
|
+
blocks the requested work and report unrelated errors separately. When it reports
|
|
71
69
|
agent files out of sync, such as an outdated skill, tell the user and suggest
|
|
72
70
|
`npx bitakit init --update-agent-files`.
|
|
73
|
-
4. Read the owning plugin's files before changing them
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
71
|
+
4. Read the owning plugin's files before changing them, starting with its `AGENTS.md` when it
|
|
72
|
+
has one. Every installed `@bitakit/*` package ships `node_modules/@bitakit/<name>/AGENTS.md`:
|
|
73
|
+
what it provides (IDs, slots, replaceable parts), how to extend or replace it and its rules.
|
|
74
|
+
Read it before using the package; its README has the details. Generated `src/bitakit.gen.*`
|
|
75
|
+
files are evidence for types; never edit them. Keep plugin-specific recipes with their owning
|
|
76
|
+
package. A configured plugin directory may differ from `src/plugins`; inspect the app.
|
|
77
77
|
5. Before placing UI, inspect the app's selected composition: which layout frames the page (Shell
|
|
78
|
-
`sidebar`, the default, or `navbar`; a page's `export const layout
|
|
78
|
+
`sidebar`, the default, or `navbar`; a page's `export const layout` family; `src/layouts/`)
|
|
79
79
|
and which component actually renders the slot you want. A declared slot shows nothing until an
|
|
80
80
|
outlet renders it.
|
|
81
81
|
|
|
82
|
+
## Choose the mechanism
|
|
83
|
+
|
|
84
|
+
Decide before writing code, and tell the user the plan in a sentence or two.
|
|
85
|
+
|
|
86
|
+
| You need | Use | File in the plugin |
|
|
87
|
+
| -------------------------------------------------------- | --------------------------------- | -------------------------------------------------------- |
|
|
88
|
+
| A screen | Page | `ui/pages/<path>.tsx` |
|
|
89
|
+
| Data or logic that pages, Actions and other features use | Service with a `store()` | `services/<name>.ts` |
|
|
90
|
+
| Something the user triggers: button, link, menu entry | Action bound with `<Action>` | `actions/<name>.ts` |
|
|
91
|
+
| A choice the user keeps after a reload | Setting | `settings.ts` |
|
|
92
|
+
| To tell other features that something happened | Event | `events.ts` |
|
|
93
|
+
| A place where other features can add buttons or UI | Slot and its outlet | `slots/<name>.ts` |
|
|
94
|
+
| Your UI in another feature's place or in the Shell | Slot contribution or Action slots | `ui/slots/<slot>.tsx` |
|
|
95
|
+
| Another layout, frame or screen (404, error, sign-in) | A file for its single slot | `src/layouts/<family>.tsx`, `ui/slots/screen.<name>.tsx` |
|
|
96
|
+
| A rule over Actions you do not own | Interceptor | `interceptors/<name>.ts` |
|
|
97
|
+
| Saved or server data, secrets, permission checks | API route and a service | `src/app/api/<name>/route.ts` |
|
|
98
|
+
|
|
82
99
|
## Implement in the owning plugin
|
|
83
100
|
|
|
84
101
|
- One feature, one plugin. Create it with `npx bitakit add plugin <name>` and add files with
|
|
85
102
|
`npx bitakit add <kind> <plugin>/<name>` (kinds: `action`, `service`, `page`, `interceptor`,
|
|
86
103
|
`config`, `slot`, `slot-definition`, `dialog`, `provider`). `events`, `settings` and
|
|
87
|
-
`settings-page` take only `<plugin>`; `layout <
|
|
104
|
+
`settings-page` take only `<plugin>`; `layout <family>[/<variant>]` writes `src/layouts/`
|
|
105
|
+
(`--plugin <id>` for a plugin's `ui/layouts/`); `test <plugin>` writes
|
|
88
106
|
`tests/<plugin>.test.ts`. Existing files are never overwritten.
|
|
89
107
|
- Folders are the default layout; flat files (`actions.add.ts`, or one `actions.ts` for several
|
|
90
108
|
Actions) declare the same IDs and are equally fine. Follow the layout the app already uses; see
|
|
91
109
|
[references/plugins-and-pages.md](references/plugins-and-pages.md#folders-or-flat-files).
|
|
92
110
|
- Replace the generated template bodies and tutorial comments with the real implementation.
|
|
93
111
|
- Extend a feature you do not own from your own plugin: listen to its events, fill its slots,
|
|
94
|
-
call its services (declared with `requires`) and read its settings. Change
|
|
95
|
-
it must offer a new contract, such as a slot it renders, and tell the user
|
|
112
|
+
replace its parts, call its services (declared with `requires`) and read its settings. Change
|
|
113
|
+
the owner only when it must offer a new contract, such as a slot it renders, and tell the user
|
|
114
|
+
why.
|
|
115
|
+
- `add plugin` writes a short `AGENTS.md` and a `CLAUDE.md` containing `@AGENTS.md` in the
|
|
116
|
+
plugin's own folder, including with `--example` and `--minimal`. Read that guide before
|
|
117
|
+
editing the plugin. Keep its actual purpose, public contracts, extension points, constraints
|
|
118
|
+
and checks there, updating them with relevant code changes. See
|
|
119
|
+
[references/plugin-guides.md](references/plugin-guides.md) for concrete examples. Include only what that plugin implements;
|
|
120
|
+
other plugins keep their own guides, and shared conventions stay in the app guide or this
|
|
121
|
+
skill. Maintain the instructions in `AGENTS.md`; discovery ignores both Markdown files.
|
|
96
122
|
- State lives in services, preferences in settings, operations in Actions bound to controls with
|
|
97
123
|
`<Action>`. Pages and components live under `ui/` and start with `'use client'` in Next.js.
|
|
98
124
|
- Use `@bitakit/ui/components` and the app's theme tokens. Keep styling to the existing
|
|
@@ -105,8 +131,18 @@ Do this once per session, before the first change:
|
|
|
105
131
|
for portaled content.
|
|
106
132
|
- Build on BitaKit's mechanisms: no own registries, event buses, settings stores or button
|
|
107
133
|
state, and no edits to generated files or the framework's provider wiring.
|
|
108
|
-
-
|
|
109
|
-
|
|
134
|
+
- Habits that prevent most bugs ([references/best-practices.md](references/best-practices.md)):
|
|
135
|
+
return the promise from `execute`; replace store values instead of changing them; read
|
|
136
|
+
settings when you use them; load data in services, not components; check permissions on the
|
|
137
|
+
server; give every list an empty, a loading and an error state.
|
|
138
|
+
- Add dependencies within the user's authorized scope. Select each BitaKit package's compatible
|
|
139
|
+
published version from the app's release line and check peer dependencies. Do not copy Core's
|
|
140
|
+
exact patch version to another package: their patch releases may differ.
|
|
141
|
+
|
|
142
|
+
Use existing tools before adding automation: `bitakit add` scaffolds, `generate` wires,
|
|
143
|
+
`info`/`slots` inspect, `doctor` diagnoses and `check-page` inspects rendered output. Use the
|
|
144
|
+
app's test runner and scripts. Add a skill-local script only for a concrete repeated operation
|
|
145
|
+
those tools cannot perform; do not recreate their logic or add placeholder scripts.
|
|
110
146
|
|
|
111
147
|
Write code a teammate can read at a glance: small files, names from the user's domain, and at
|
|
112
148
|
most one short comment per non-obvious decision that says why. Do not comment what the code
|
|
@@ -114,9 +150,14 @@ already says.
|
|
|
114
150
|
|
|
115
151
|
## Check the result
|
|
116
152
|
|
|
153
|
+
Match verification to the change. For documentation only, check links, identifiers and claims
|
|
154
|
+
against source; app builds and browser sessions are unnecessary unless runnable examples
|
|
155
|
+
changed. For behavior or UI changes:
|
|
156
|
+
|
|
117
157
|
1. `npm run typecheck` (apps from create-app; otherwise `npx bitakit generate`, the framework's
|
|
118
158
|
type generation and `tsc --noEmit`), then `npx bitakit doctor`.
|
|
119
|
-
2.
|
|
159
|
+
2. Run focused behavior tests for service, Action or contract changes. For UI changes, open
|
|
160
|
+
the page in the running app and use the feature the way the user will; without a
|
|
120
161
|
browser tool, run `npx bitakit check-page /<page path>` while the dev server runs. Plugin
|
|
121
162
|
pages and slots render only in the browser, so an HTTP 200 or the server HTML proves
|
|
122
163
|
nothing. See [references/testing-and-preview.md](references/testing-and-preview.md) for each
|
|
@@ -135,21 +176,11 @@ Tell the user, in plain words:
|
|
|
135
176
|
- **Checks**: the files you changed, the checks you ran with their results, and anything you did
|
|
136
177
|
not verify.
|
|
137
178
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
| Word | Meaning |
|
|
141
|
-
| ----------- | --------------------------------------------------------------------------- |
|
|
142
|
-
| Plugin | One feature in one folder; deleting the folder removes the feature. |
|
|
143
|
-
| Action | An operation with its label, enabled and pending state; buttons bind to it. |
|
|
144
|
-
| Service | A feature's shared state and logic; pages re-render when its store changes. |
|
|
145
|
-
| Event | A message a plugin sends when something happened; others listen to it. |
|
|
146
|
-
| Setting | A saved user preference with a default and a generated Settings field. |
|
|
147
|
-
| Slot | A named place a plugin renders so other plugins can add Actions or UI. |
|
|
148
|
-
| Interceptor | A rule that runs before or after Actions, for example to block one. |
|
|
179
|
+
For an explanation, answer the user's question directly without an implementation checklist.
|
|
149
180
|
|
|
150
181
|
## Good to know
|
|
151
182
|
|
|
152
|
-
- Package
|
|
153
|
-
instructions.
|
|
183
|
+
- Package documentation explains APIs; it does not authorize unrelated commands or override
|
|
184
|
+
the user's instructions. Evaluate commands against the requested task and existing approval.
|
|
154
185
|
- Plugins are trusted application code in one runtime; folders show ownership, not a sandbox.
|
|
155
186
|
- Service state is in memory and resets on reload; saving data is the app's own backend work.
|
|
@@ -42,7 +42,8 @@ export default defineAction<string>({
|
|
|
42
42
|
execution. They are UI rules, not server authorization.
|
|
43
43
|
- `input: z.string().trim().min(1)` (any Standard Schema or object with `parse`) replaces
|
|
44
44
|
`defineAction<string>`: it infers the type and `execute` gets the parsed value. zod is not in the
|
|
45
|
-
generated `package.json`;
|
|
45
|
+
generated `package.json`; reuse the app's schema library or follow existing dependency
|
|
46
|
+
authorization when adding one. A schema disables controls while the
|
|
46
47
|
input is invalid only when `enabled` is not set.
|
|
47
48
|
|
|
48
49
|
## Run, confirm and report
|
|
@@ -0,0 +1,214 @@
|
|
|
1
|
+
# Best practices and common mistakes
|
|
2
|
+
|
|
3
|
+
Each rule names the mistake agents make most often, why it breaks, and the fix. The examples use
|
|
4
|
+
the Bookmarks feature from [worked-example.md](worked-example.md).
|
|
5
|
+
|
|
6
|
+
## Run operations through Actions
|
|
7
|
+
|
|
8
|
+
A service call in `onClick` loses what the Action provides: disabled and pending state, the
|
|
9
|
+
confirmation, success and failure messages, interceptors and keyboard shortcuts.
|
|
10
|
+
|
|
11
|
+
```tsx
|
|
12
|
+
// ✗ No pending state, no confirmation, errors vanish.
|
|
13
|
+
<Button onClick={() => services.bookmarks.list.remove(bookmark.id)}>Remove</Button>
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
```tsx
|
|
17
|
+
// ✓ The Action owns the label, guards and messages.
|
|
18
|
+
<Action id="bookmarks.remove" input={bookmark.id}>
|
|
19
|
+
<Button variant="outline" size="sm" />
|
|
20
|
+
</Action>
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
For a control that needs its own markup, use `useAction(id).props()` ([actions.md](actions.md)).
|
|
24
|
+
|
|
25
|
+
## Read service state with a selector; do not copy it
|
|
26
|
+
|
|
27
|
+
Copying a store into React state shows stale data and renders twice.
|
|
28
|
+
|
|
29
|
+
```tsx
|
|
30
|
+
// ✗ A second copy that drifts from the service.
|
|
31
|
+
const [bookmarks, setBookmarks] = useState<Bookmark[]>([]);
|
|
32
|
+
useEffect(() => setBookmarks(service?.state.get().bookmarks ?? []), [service]);
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
```tsx
|
|
36
|
+
// ✓ Re-renders only when the selected value changes; [] until the service is ready.
|
|
37
|
+
const bookmarks = useServiceState('bookmarks.list', (state) => state.bookmarks, []);
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Select the smallest value a component needs, such as `state.bookmarks.length` for a counter.
|
|
41
|
+
|
|
42
|
+
## Replace store values; never change them in place
|
|
43
|
+
|
|
44
|
+
`state.set` is what notifies pages and Actions. Changing the current value does not.
|
|
45
|
+
|
|
46
|
+
```ts
|
|
47
|
+
// ✗ Nothing re-renders; other readers see a changed array without notice.
|
|
48
|
+
state.get().bookmarks.push(bookmark);
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
```ts
|
|
52
|
+
// ✓ A new array, and every reader updates.
|
|
53
|
+
state.set((current) => ({ ...current, bookmarks: [...current.bookmarks, bookmark] }));
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## Return the promise from `execute`
|
|
57
|
+
|
|
58
|
+
The Action waits for what `execute` returns. Without a return the run ends at once, the button
|
|
59
|
+
is not pending, and a failure becomes an unhandled rejection instead of a message.
|
|
60
|
+
|
|
61
|
+
```ts
|
|
62
|
+
// ✗ Braces without return: completes immediately, errors are lost.
|
|
63
|
+
execute: ({ services, input }) => {
|
|
64
|
+
services.bookmarks.list.add(input);
|
|
65
|
+
},
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
```ts
|
|
69
|
+
// ✓
|
|
70
|
+
execute: ({ services, input }) => services.bookmarks.list.add(input),
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## Read settings when you use them
|
|
74
|
+
|
|
75
|
+
A service factory runs before stored settings load, so a value read there stays at its default.
|
|
76
|
+
|
|
77
|
+
```ts
|
|
78
|
+
// ✗ Always the default value.
|
|
79
|
+
export default defineService(({ settings }) => {
|
|
80
|
+
const newTab = settings.bookmarks.openInNewTab.get();
|
|
81
|
+
// ...
|
|
82
|
+
});
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
// ✓ Read inside the method, at call time.
|
|
87
|
+
open(url: string) {
|
|
88
|
+
window.open(url, settings.bookmarks.openInNewTab.get() ? '_blank' : '_self');
|
|
89
|
+
},
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
In React, use `useSetting('bookmarks.openInNewTab').value`; in Actions, the `settings` argument.
|
|
93
|
+
|
|
94
|
+
## Reach other features through their contracts
|
|
95
|
+
|
|
96
|
+
Importing another plugin's files ties the two folders together: removing or renaming one breaks
|
|
97
|
+
the other, and the import bypasses startup order and the missing-service check.
|
|
98
|
+
|
|
99
|
+
```ts
|
|
100
|
+
// ✗ In src/plugins/sharing: reaches into another plugin's folder.
|
|
101
|
+
import list from '../../bookmarks/services/list';
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
```ts
|
|
105
|
+
// ✓ src/plugins/sharing/actions/copy-links.ts: the service by name, declared as a dependency.
|
|
106
|
+
import { defineAction } from '@bitakit/core';
|
|
107
|
+
|
|
108
|
+
export default defineAction({
|
|
109
|
+
title: 'Copy all links',
|
|
110
|
+
requires: ['bookmarks.list'],
|
|
111
|
+
execute: ({ services }) =>
|
|
112
|
+
navigator.clipboard.writeText(
|
|
113
|
+
services.bookmarks.list.state
|
|
114
|
+
.get()
|
|
115
|
+
.bookmarks.map((bookmark) => bookmark.url)
|
|
116
|
+
.join('\n'),
|
|
117
|
+
),
|
|
118
|
+
});
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Read the state with `useServiceState`, react to `bookmarks.added` with `events.on`, and add UI
|
|
122
|
+
through the owner's slots. A type-only import in a test is fine.
|
|
123
|
+
|
|
124
|
+
## Place UI with `slots`, not `groups`
|
|
125
|
+
|
|
126
|
+
`groups` is a logical label for queries; it never renders anything.
|
|
127
|
+
|
|
128
|
+
```ts
|
|
129
|
+
// ✗ Appears nowhere.
|
|
130
|
+
defineAction({ title: 'Bookmarks', href: '/bookmarks', groups: ['navigation'] });
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
```ts
|
|
134
|
+
// ✓ Shell renders it in the navigation.
|
|
135
|
+
defineAction({ title: 'Bookmarks', href: '/bookmarks', slots: ['shell.navigation'] });
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
## Load data in services, not in components
|
|
139
|
+
|
|
140
|
+
A `fetch` in a page runs again on every visit, is not shared with Actions or other features,
|
|
141
|
+
and leaves loading and error handling to each component. Load in the service's `onStart`, keep
|
|
142
|
+
`status` and `error` in its store, and let pages render them
|
|
143
|
+
([data-and-api.md](data-and-api.md)).
|
|
144
|
+
|
|
145
|
+
## Emit your own events after the change
|
|
146
|
+
|
|
147
|
+
Only the declaring plugin emits its events, and only after its state changed, so listeners read
|
|
148
|
+
the new state. To react to another feature, listen to its event; to need a new one, add it in
|
|
149
|
+
the owner.
|
|
150
|
+
|
|
151
|
+
```ts
|
|
152
|
+
// ✗ Emitted before the change, and from a plugin that does not own the event.
|
|
153
|
+
events.emit('bookmarks.added', { id, url });
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
```ts
|
|
157
|
+
// ✓ In the bookmarks service, after state.set(...).
|
|
158
|
+
events.emit('bookmarks.added', { id: bookmark.id, url: bookmark.url });
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
## Enforce permissions on the server
|
|
162
|
+
|
|
163
|
+
`enabled`, `visible`, `confirm` and interceptors shape the UI in the browser. Anyone can call
|
|
164
|
+
the API directly, so the API route checks the session and the input again.
|
|
165
|
+
|
|
166
|
+
## Give every list its states
|
|
167
|
+
|
|
168
|
+
Show an empty state ("No bookmarks yet"), a loading placeholder (`Skeleton`) and an error with a
|
|
169
|
+
retry Action. A blank area looks broken.
|
|
170
|
+
|
|
171
|
+
## Keep the generated and template code out of the result
|
|
172
|
+
|
|
173
|
+
- Never edit `src/bitakit.gen.*`; change the source file and run `npm run typecheck`.
|
|
174
|
+
- Replace template bodies, placeholder subtitles and tutorial comments from `bitakit add`, and
|
|
175
|
+
delete files the feature does not use.
|
|
176
|
+
- Keep one feature in one plugin folder: deleting the folder removes the feature and nothing else.
|
|
177
|
+
|
|
178
|
+
## Replace parts through their slot, never by editing the owner
|
|
179
|
+
|
|
180
|
+
A sign-in frame, a 404 page or another plugin's card is a replaceable part (a single slot). Put
|
|
181
|
+
your version in your own folder and leave the owner unchanged.
|
|
182
|
+
|
|
183
|
+
```text
|
|
184
|
+
✗ Editing node_modules/@bitakit/shell or another team's plugin to change its not-found page.
|
|
185
|
+
✓ src/plugins/brand/ui/slots/screen.not-found.tsx (or src/layouts/auth.tsx for a layout)
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
Deleting your file brings the default back. With several candidates, decide in
|
|
189
|
+
`bitakit.config.ts` (`choose`); see [layouts-and-screens.md](layouts-and-screens.md).
|
|
190
|
+
|
|
191
|
+
## Let a plugin introduce itself
|
|
192
|
+
|
|
193
|
+
Every installed `@bitakit/*` package ships an `AGENTS.md` with its IDs, extension points and
|
|
194
|
+
rules; read `node_modules/@bitakit/<name>/AGENTS.md` before using it. `bitakit add plugin <id>`
|
|
195
|
+
starts a local guide and a `CLAUDE.md` importing it. Keep `src/plugins/<id>/AGENTS.md` specific
|
|
196
|
+
to that plugin: its purpose, what it owns
|
|
197
|
+
(services, Actions, events, settings, slots and replaceable parts), how other features extend
|
|
198
|
+
or replace it, and its constraints and checks. Document only implemented contracts, keep the
|
|
199
|
+
guide current with the code, and keep other plugins' details in their own folders. The shared
|
|
200
|
+
app guide and skill describe conventions, not individual plugins' specifications.
|
|
201
|
+
|
|
202
|
+
## Name things after the domain
|
|
203
|
+
|
|
204
|
+
| Kind | Form | Examples |
|
|
205
|
+
| ------- | ------------------------------ | ------------------------------------- |
|
|
206
|
+
| Plugin | The feature, usually a noun | `bookmarks`, `billing`, `team` |
|
|
207
|
+
| Action | A verb, optionally with object | `add`, `remove`, `open`, `export-csv` |
|
|
208
|
+
| Service | What it holds | `list`, `feed`, `cart` |
|
|
209
|
+
| Event | What happened, past tense | `added`, `removed`, `changed` |
|
|
210
|
+
| Setting | The preference, in camelCase | `limit`, `openInNewTab` |
|
|
211
|
+
| Slot | Where it renders | `toolbar`, `footer`, `row.menu` |
|
|
212
|
+
|
|
213
|
+
The plugin ID prefixes every name, so `bookmarks.add` reads as a sentence; do not repeat the
|
|
214
|
+
plugin in the file name (`actions/add.ts`, not `actions/add-bookmark.ts`).
|